Oppy for AI agents

Overview

Oppy's MCP server lets an AI assistant work your card inbox directly — reading buying signals, deciding which are worth pursuing, revealing contacts and pushing them into your CRM. No integration code.

It speaks the Model Context Protocol, so any MCP-compatible client can connect: the Claude app, Claude Code, Cursor, or an agent you build yourself.

The server exposes the same capabilities as the REST API, governed by the same permissions, the same credit costs and the same rate limits. Anything an agent does through it, you could have done with a curl command.

Prerequisites

Before connecting, you need:

• An active Oppy account.
• API access enabled for your workspace. This is switched on by Oppy — email contact@oppyone.com if you are not sure whether yours is. Without it every request returns "not found".
• Admin permissions in Oppy, if you plan to connect with an API key (creating keys is admin-only).
• Available credits, if you want your agent to reveal contact details.

Connecting

Endpoint	https://api.oppyone.com/mcp
Transport	Streamable HTTP
Authentication	OAuth 2.0, or an Oppy API key

Two credentials work. OAuth signs you in with your Oppy account and needs no key — use it for the Claude app. An API key carries whatever scopes you gave it — use it for Claude Code, Cursor, and agents you run yourself.

Claude — web, desktop and mobile

1. Open Settings → Connectors and click Add custom connector.
2. Enter https://api.oppyone.com/mcp as the URL.
3. Open Advanced settings and enter the OAuth Client ID W1stSlHF9i5BsRKT. Leave the Client Secret empty.
4. Click Connect. You are redirected to Oppy to approve access, then returned to Claude automatically.
5. Oppy's tools now appear in the conversation.

Your agent acts as you, with your workspace's full permissions — no key is created and nothing is pasted into a chat.

Claude Code

Claude Code uses an API key. Create one in the Oppy dashboard under Workspace settings → API keys, then:

claude mcp add --transport http oppy https://api.oppyone.com/mcp \
  --header "Authorization: Bearer $OPPY_API_KEY"

note

Claude Code and the Claude app keep separate connector stores. A server added with claude mcp add does not appear in the Claude app, and a connector added in the Claude app does not appear in Claude Code. Set up each one you use.

Cursor and other MCP clients

Point the client at https://api.oppyone.com/mcp over streamable HTTP and send your key as a header — either form works:

Authorization: Bearer oppy_live_...
X-API-Key: oppy_live_...

Clients that support the MCP authorization spec can use OAuth instead: they discover it automatically from the endpoint, and you sign in with your Oppy account rather than configuring a key.

Available tools

Only the tools your credential permits are listed. A key holding just cards:read sees three tools — so a read-only key gives you a read-only agent, with no separate setting to configure. An OAuth connection sees all eleven.

Tool	What it does	Scope	Cost
get_workspace_context	Your workspace, the people cards can be assigned to, and your credit balance	workspace:read	Free
list_cards	Your card inbox, best first	cards:read	Free
get_card	One card in full, including its narrative text	cards:read	Free
list_contact_candidates	Who could be revealed at that company — names and titles only	contacts:read	Free
list_revealed_contacts	Contacts on a card you have already paid for, with full details	contacts:read	Free
hydrate_card	Generates a card's trigger, relevance and strategy text	cards:write	Free
approve_card	Approves a card and starts the contact lookup	cards:write	Free
reject_card	Rejects a card, optionally with a reason	cards:write	Free
update_card	Moves a card along your pipeline, or reassigns it	cards:write	Free
reveal_contact	Reveals a contact's email, LinkedIn and optionally phone	contacts:write	1 credit, 6 with phone
push_card_to_crm	Creates the contact and company in your CRM with a context note	crm:write	Free

Cards come back best first — hot, then warm, then cold, then evergreen, and within each tier the strongest signals first. Your agent does not need to page through a large inbox to find the good ones; they are on the first page.

Sample prompts

Triage the inbox

Show me my top pending cards. For the hot ones, hydrate them and tell me which three are worth pursuing this week and why.

Research before outreach

What is the signal on the Storyblok card, and what would you open with?

Reveal and push

Find the best contact at Bitwig, reveal their email, and push the card to HubSpot.

Keep the pipeline current

Mark the Omio card as contacted and assign it to me.

Clean up

Reject any pending card where the company is under 20 people, and say why in each rejection.

Rejections with a reason feed your ICP refinement, so the cards you get next week improve. A bare rejection does not.

Credits

Revealing a contact spends your workspace's credits:

• 1 credit for email and LinkedIn.
• 6 credits if you also ask for a phone number.
• Nothing to reveal someone you have already paid for on that card — check list_revealed_contacts first.

Everything else is free.

Two things worth knowing before you let an agent loose:

Revealing approves the card. Paying for a contact is a stronger commitment than clicking approve, so a pending card does not stay in your inbox after you have paid for someone on it.

Your agent must state the price. Every reveal has to declare the exact number of credits it is authorising, and Oppy rejects the call if it does not match. Nothing is charged when that happens. This exists because MCP clients can be configured to approve tool calls automatically, and a credit spend is not refundable — so an accidental reveal becomes a rejected one rather than a surprise on your bill.

Rate limits

Counted per workspace, not per credential — connecting a second agent does not buy extra capacity, and the MCP server shares its budget with the REST API.

Requests	Burst	Sustained
Reads	20 / sec	120 / min
Writes — approve, reject, update	10 / sec	60 / min
Hydrate — pre-generated	20 / sec	120 / min
Hydrate — needs generation	2 / sec	20 / min
Reveal	5 / sec	30 / min
Push to CRM	5 / sec	30 / min

Hydration has two speeds. Most cards carry a pre-generated insight and hydrate in seconds under the generous limit; the rest need real generation and get the tight one. You do not choose — Oppy decides per card. In practice this only bites when an agent tries to hydrate a whole page at once, so ask it to hydrate the cards you actually intend to read.

Support & Troubleshooting

• Questions or issues: contact@oppyone.com

What you see	What it means
No tools appear at all	The key is wrong or revoked, or your workspace does not have API access enabled yet.
Fewer tools than you expected	Your key does not carry those scopes. Create a key with the scopes you need — this is working as intended.
Tools are listed, but every call returns "not found"	Your workspace does not have API access enabled. Email us.
"confirm_credits must be 6"	The agent asked for a phone number, which costs 6 credits rather than 1. Nothing was charged.
"payment_required"	Your monthly reveal credits are exhausted. get_workspace_context shows the balance.
Hydration is rate-limited	That card needed real generation. Hydrate cards one at a time rather than a page at once.
The Claude app cannot find your connector	claude mcp add only registers with Claude Code. Add it in the Claude app separately — see Connecting.