Connect and authenticate

Connect your agent host to Thirdfy MCP and choose how it proves who it acts for. Thirdfy hosts the endpoint, so there is nothing to install. For setup in a specific app, see the MCP client guides.

You can connect in three ways:

Endpoint

Every tool listed by GET /tools works on both /mcp and /tool/<toolName>.

Your agent key goes in the header

Thirdfy MCP doesn't remember you between calls. It identifies your agent from the connection header on every request:

Authorization: Bearer agent-...

X-API-KEY: agent-... works too.

• With the header, Thirdfy checks the key and fills it in as agentApiKey on every tool call. Your agent can act only for itself. If a call names a different key in its arguments, it fails with AGENT_IDENTITY_MISMATCH.
• Without the header, plain /mcp answers 401 and asks you to sign in (see the next section).
• For keyless use, connect to https://mcp.thirdfy.com/mcp/public. Only the tools that need no key work there. A tool that needs a key returns 401 Authentication required, even when the key is in the tool arguments.

To get a key:

1. Run email onboarding (startEmailOnboarding, then completeEmailOnboarding).
2. Save the key. It is returned once, at data.bootstrap.agentApiKey.
3. Add it to your connector and reconnect.

Sign in instead of a key

In a chat app you can use your Thirdfy account instead of an agent key. This works in apps that support MCP sign-in: claude.ai, Claude Desktop, Claude Code, ChatGPT and Cursor.

1. Add https://mcp.thirdfy.com/mcp to the app.
2. The app opens auth.thirdfy.com. Sign in the way you do on thirdfy.com (email, Google or wallet).
3. Choose one agent, or click + Create a new agent.
4. Choose what the app gets:

If you granted Read only, a write returns 403 insufficient_scope and the app asks you to sign in again with mcp:trade.

See or revoke connected apps at auth.thirdfy.com/connections. An app keeps access only while you own the agent. After an ownership change, its access stops within the hour.

Hosted agents and servers keep using the agent key header.

For developers: the app finds the sign-in details in the 401 reply (/.well-known/oauth-protected-resource/mcp).

What a signed-in app can do

A signed-in app acts for the one agent you chose, with these 17 tools: health, listTools, getThirdfyHelp, getActionsCatalog, getProviderActions, getChainCapabilities, getNonEvmCapabilities, walletExecute, previewOrder, agentWalletBootstrap, getWalletProfile, getVenueReadiness, prepareVenueOnboarding, completeVenueOnboarding, fundVenue, getCreditsBalance and quoteActionPricing.

• Each write asks you to confirm first, with a form in the chat or a CONFIRMATION_REQUIRED reply that carries a confirmationToken. See Write confirmation.
• agentRun, executeIntent, onboarding, delegation and typed toolsets are not available. Use the agent key for those.
• Lighter isn't offered in signed-in apps yet, because it needs manual setup (an account index, an API key index and integer units). It works with an agent key: the Agent CLI, the API, or MCP with the key header. In a signed-in app, naming Lighter returns VENUE_NOT_AVAILABLE.
• Very large read replies are cut off at 80 KiB.

Credential modes

Each tool call runs under one kind of credential. Most people only need sign-in or an agent key.

Tools that need no key

On https://mcp.thirdfy.com/mcp/public: getThirdfyHelp, getActionsCatalog, getProviderActions, getChainCapabilities, getNonEvmCapabilities, describeOnboardingPath, startEmailOnboarding, completeEmailOnboarding, startWalletOnboarding, completeWalletOnboarding, health, listTools, and the public signal reads (for example get_cmc_fear_greed, get_openmarket_btc_funding).

Tools a bootstrap token may call

A bootstrap token is for setup only. It may call agentRegister, bootstrapSelfIdentity, getSelfReadiness, managedWalletInit, managedWalletGrant, managedWalletStatus, agentWalletBootstrap, the delegation* setup and World ID tools, the consoleMandate* tools, and walletExecute on the agent_wallet lane.

You get a bootstrap token by proving a session (ownerSessionToken or authToken) or a wallet (challengeId + signature).

For every tool and the credentials it accepts, see the Tools reference.

Direct tool calls

Scripts can call any tool over plain HTTP, without an MCP session:

curl -s https://mcp.thirdfy.com/health

curl -s -X POST https://mcp.thirdfy.com/tool/getProviderActions \
  -H "Content-Type: application/json" \
  -d '{"provider":"openmarket","view":"concise"}'

curl -s -X POST https://mcp.thirdfy.com/tool/agentRun \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -d '{"action":"get_openmarket_btc_funding"}'

getProviderActions accepts provider or providerId.

Hosted runtimes can add executionContext (runtimeId, orgId) to walletExecute, executeIntent and agentRun, so credits are charged to the right runtime.

HTTP errors

A call can pass sign-in or the key check and still be refused. Thirdfy's checks run on every write: allowlist, daily limit, delegation, venue readiness and credits. If any check fails, nothing runs.

CEX credentials

Never send exchange (CEX) API keys through MCP; it doesn't accept them. The Thirdfy API stores them, and tools pass a credentialRef that points to them. See CEX integrations.

Security

The MCP endpoint is public, so don't rely on it to guard your secrets. Keep the agent key in your host's connector settings or a secret store, never in prompts. Never give an agent an operator or full platform key.

Related

• MCP client guides
• Onboarding
• Discovery
• Agent CLI authentication