Content
# Thirdfy MCP
Production MCP server for Thirdfy execution and governance flows, built on Cloudflare Workers.
## Why This MCP Exists
Thirdfy MCP is the managed-agent connector layer for:
- execution discovery (`getActionsCatalog`, `getAgentActions`)
- lane/capability negotiation (`getChainCapabilities`, `getNonEvmCapabilities`)
- fail-closed execution (`executeIntent`, `getIntentStatus`, `buildTx`)
- managed self-signer execution (`walletExecute`, `walletSign`, `walletSubmit`, `agentRun`)
- delegation and wallet governance (`delegation*`, `managedWallet*`, `agentRegister`, `getSelfReadiness`)
This service is optimized for Claude Managed Agents and any MCP-native runtime.
## Transport and Authentication
- MCP connector path: `POST /mcp` (streamable HTTP)
- Tool endpoint path: `POST /tool/<toolName>`
- Public routes: `GET /health`, `GET /tools`, `GET /chat/capabilities`
- Credentialed read route: `GET /agents` (requires bootstrap/agent/full credential mode)
Credential modes:
- `none`: public discovery + MCP `initialize` / `tools/list` and explicitly allowlisted safe read tools only
- `bootstrap` (`btp...`): short-lived onboarding token from `POST /auth/bootstrap/issue`
- `agent_api_key` (`agent-...`): preferred execution identity for managed sessions
- `full_api_key`: operator/server credential for privileged maintenance paths
Auth policy is enforced per tool `authProfile` across `/mcp` and `/tool/*`.
## Security Boundary
This MCP is a public edge surface, not a trust boundary by itself.
- Discovery routes are intentionally public (`/health`, `/tools`, selected MCP discovery methods).
- `GET /agents` is authenticated and policy-gated to avoid exposing private agent payloads.
- Privileged execution and sensitive reads require credentialed access modes.
- Backend policy remains fail-closed: if identity/delegation/policy checks fail, writes are blocked.
- Keep private API credentials and `.dev.vars` secrets out of source control and rotate regularly.
See `SECURITY.md` for reporting and hardening guidance.
## Managed Flow Contract
Credential modes:
- `none`: discovery-only endpoints and explicitly allowlisted tools.
- `bootstrap`: scoped bootstrap token for onboarding and controlled setup tools.
- `agent_api_key`: delegated execution tools for managed agents.
- `full_api_key`: full platform authority (private integrations).
Failure semantics:
- `401/403`: authentication/authorization denied by credential mode or tool policy.
- `404`: unknown route/tool.
- `429`: rate-limited.
- `5xx`: upstream/private API failure.
Anonymous-safe read tools:
- `getActionsCatalog`
- `getChainCapabilities`
- `getNonEvmCapabilities`
- `listTools`
Bootstrap issuance supports both:
- `session_token` proof (`ownerSessionToken` / `authToken`)
- `wallet_signature` proof (`challengeId` + `signature`) verified through the onboarding verifier route
## Tool Surface
### Core tools (default discovery)
- `getActionsCatalog`
- `getAgentActions`
- `getChainCapabilities`
- `getNonEvmCapabilities`
- `executeIntent`
- `walletExecute`
- `walletSign`
- `walletSubmit`
- `agentRun`
- `getIntentStatus`
- `buildTx`
- `delegationCreate`
- `delegationActivate`
- `delegationStatus`
- `delegationRevoke`
- `delegationInspect`
- `delegationBalance`
- `delegationRedeem`
- `managedWalletInit`
- `managedWalletGrant`
- `managedWalletStatus`
- `agentRegister`
- `bootstrapSelfIdentity`
- `getSelfReadiness`
- `health`
- `listTools`
### Compatibility tools (hidden by default)
Enable with `ENABLE_COMPAT_TOOLS=true`.
- protocol reads (`getCurrentEpoch`, gauges/rewards/dashboard)
- chat/docs reads (`universalChat`, `getChatCapabilities`, `searchThirdfyDocs`)
- credentialed agent listing helper (`listAgents`)
## Recommended Execution Sequence
For any write flow:
0. onboarding/bootstrap (once per identity):
- `agentRegister` (creator registration)
- `bootstrapSelfIdentity` (scoped identity bootstrap/rotation)
- `managedWalletInit` / `managedWalletGrant` as needed for managed lanes
1. `getActionsCatalog`
2. `getAgentActions`
3. `getChainCapabilities` (or `getNonEvmCapabilities`)
4. governance/readiness gate
- `self`: `getSelfReadiness` (delegation optional)
- `hybrid` / `thirdfy`: `delegationStatus` required
5. choose write rail
- managed self-wallet: `walletExecute` (default for Claude managed self execution)
- fanout/subscriber lane: `executeIntent`
- BYOW signing: `walletSign` then `walletSubmit`
6. poll `getIntentStatus` only for execute-intent fanout jobs; for `walletExecute` use direct tx result fields (`txHash`, `blockedReason`, `blockedStage`)
`delegationRedeem` is a convenience helper over `executeIntent` and supports
`runMode=thirdfy|hybrid|agent_wallet` with optional `hybridWalletMode` and `mirrorOnly`.
Fail-closed behavior:
- `hybrid` / `thirdfy`: block writes if governance/policy/delegation fails.
- `self`: delegation may be absent, but policy/readiness failures still block.
## Quickstart (Local)
```bash
npm install
cp .env.example .dev.vars
```
Minimum `.dev.vars`:
```env
THIRDFY_API_KEY=your-thirdfy-api-key
USE_MOCK_DATA=true
ENABLE_COMPAT_TOOLS=false
MCP_BOOTSTRAP_AUTH_ENABLED=true
MCP_PUBLIC_MCP_DISCOVERY_ENABLED=true
THIRDFY_BOOTSTRAP_AUDIENCE=thirdfy-mcp
THIRDFY_BOOTSTRAP_TOKEN_TTL_SECONDS=900
THIRDFY_BOOTSTRAP_TOKEN_SECRET=replace-with-long-random-secret
MCP_SERVER_VERSION=<match-package.json-version>
THIRDFY_BOOTSTRAP_SESSION_VERIFY_URL=https://api.thirdfy.com/api/v1/agent/onboarding/wallet/validate-session
THIRDFY_BOOTSTRAP_SESSION_VERIFY_TIMEOUT_MS=10000
MCP_SUPPORTED_EVM_CHAIN_IDS=8453,1,10,42161,84532
MCP_SUPPORTED_NON_EVM_CHAINS=solana
```
Run:
```bash
npx wrangler dev --port 8788
```
Smoke checks:
```bash
BASE_URL="${BASE_URL:-https://mcp.thirdfy.com}"
curl -s "$BASE_URL/health"
curl -s "$BASE_URL/tools"
curl -s -X POST "$BASE_URL/tool/getActionsCatalog" \
-H "Content-Type: application/json" \
-d '{}'
curl -s -X POST "$BASE_URL/tool/executeIntent" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <agent-api-key>" \
-d '{"agentApiKey":"agent-...","action":"preflight","chainId":8453}'
```
For local development, override:
```bash
export BASE_URL="http://localhost:8788"
```
## Build and Validation
```bash
npx tsc --noEmit
npm run build
npm test
npm run release:validate
```
Focused integration:
```bash
BASE_URL="http://localhost:8788" npm test -- tests/integration.test.ts
```
## Caching and Safety
- deterministic TTL caching (no pseudo-LRU key-list eviction)
- governance/session-sensitive tools are not cached
- structured non-secret logs only
## Deployment
1. Bump release version in `package.json` and `package-lock.json`.
2. Update release notes in `docs/releases/`.
3. Run validation gates.
4. Deploy:
```bash
npm run deploy:local
```
Local token flow (recommended):
1. Create `.env.local` (already gitignored) with:
- `CLOUDFLARE_ACCOUNT_ID=<your-account-id>`
- `CLOUDFLARE_API_TOKEN=<your-api-token>`
2. Run `npm run deploy:local` for publish and `npm run dev:local` for local wrangler dev.
Post-deploy smoke:
```bash
curl -s https://<worker-subdomain>.workers.dev/health
curl -s https://<worker-subdomain>.workers.dev/tools
```
## Documentation
- `docs/releases/README.md`
- `docs/releases/v*.md`
- `SECURITY.md`
