MCP authentication

Credential modes, anonymous-safe tools, bootstrap tokens, and HTTP failure semantics for Thirdfy MCP.

Auth policy is enforced per tool across /mcp and /tool/*. Backend execution remains fail-closed even when MCP accepts a call.

Credential modes

ModeToken shapeTypical use
noneNo credentialPublic discovery, allowlisted read tools
bootstrapbtp...Short-lived onboarding from POST /auth/bootstrap/issue
agent_api_keyagent-...Managed agent execution (preferred)
full_api_keyOperator keyPrivileged maintenance and private integrations

Bootstrap issuance supports:

  • Session proof: ownerSessionToken or authToken
  • Wallet proof: challengeId + signature via the onboarding verifier route

Anonymous-safe read tools

Callable without credentials (illustrative list):

  • getActionsCatalog
  • getProviderActions
  • getChainCapabilities
  • getNonEvmCapabilities
  • getThirdfyHelp
  • describeOnboardingPath
  • startEmailOnboarding
  • completeEmailOnboarding
  • listTools

All writes, delegation mutations, wallet execution, and portfolio reads require credentialed modes per tool authProfile.

Bootstrap-allowed tools

Bootstrap tokens may call setup tools such as agentRegister, managedWalletInit, delegationCreate, agentWalletBootstrap, and walletExecute when policy allows. Full matrix: Tools reference.

HTTP failure semantics

CodeMeaning
401 / 403Credential mode or tool policy denied
404Unknown route or tool
429Rate limited
5xxUpstream Thirdfy API failure

CEX credentials

MCP never accepts raw Bitfinex (or other CEX) API keys. Tools pass credentialRef metadata to Thirdfy API only. Store credentials with the CLI or API; see Bitfinex integration.

Related

Connect to Thirdfy MCP
Production MCP endpoint, streamable HTTP transport, Cursor and Claude setup, and direct tool calls without a self-hosted repo.
MCP discovery tools
getActionsCatalog, getProviderActions, getAgentActions, chain capabilities, and MCP resources.