Coinbase AgentKit + Forge MCP — local setup

How to merge AgentKit wallet tools into local Forge MCP for dev — and why CDP credentials never ship to production Hetzner.

Last updated: May 26, 2026 · Published 2026-05-26

Coinbase AgentKit can merge wallet and ERC-20 tools into a local Forge MCP server — local development only. Production Forge MCP on Hetzner (Option A) exposes nine Forge vault tools with zero CDP credentials. This guide covers the three-wallet model, `mcp-server/.env` setup, and the hard rule: never deploy CDP keys to production MCP and never deposit vault USDC from the CDP experimental wallet.

Three-wallet model (memorize)

AgentKit merge adds CDP wallet tools (`WalletActionProvider_*`, `Erc20ActionProvider_*`) alongside Forge vault tools when `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`, and `CDP_WALLET_SECRET` are set in gitignored `mcp-server/.env`. Startup log: `[forge-mcp] AgentKit tools merged`. Production Hetzner deploy script **strips all `CDP_*` vars** before upload — confirmed Option A custody posture.

When to use AgentKit merge vs production MCP

• Production integrators: `https://mcp.forgetreasury.com/mcp` — Forge tools only, remote Streamable HTTP.
• Local full stack: `pnpm mcp:dev` + `mcp-server/.env` — Forge + AgentKit for dev experiments.
• CDP quickstart: `cdp-wallet/` standalone project for faucet and send-tx smoke tests on Base Sepolia.
• Never: CDP credentials on Hetzner, vault deposits from CDP wallet, or Option B without CTO approval.

Prerequisites

• Coinbase Developer Platform account — portal.cdp.coinbase.com.
• Secret API key (`CDP_API_KEY_ID` + `CDP_API_KEY_SECRET` PEM).
• Wallet Secret (`CDP_WALLET_SECRET`) from Server Wallet → Accounts.
• Monorepo clone with `mcp-server/` and optional `cdp-wallet/` directories.
• Acceptance that Forge contracts are unaudited — Risks & Disclosures.

Step 1 — Audit existing credentials

Before creating duplicate API keys, check gitignored `mcp-server/.env`. AgentKit ≥ 0.10 accepts `CDP_API_KEY_ID` / `CDP_API_KEY_SECRET`; legacy `CDP_API_KEY_NAME` / `CDP_API_KEY_PRIVATE_KEY` still work as a deprecation shim. Reuse the same Secret API key in `cdp-wallet/.env` if both projects need CDP access.

Step 2 — Configure mcp-server/.env (local only)

Copy from `mcp-server/.env.example`. Fill CDP fields from the portal — never commit this file. Example shape (placeholders only):

• `CDP_API_KEY_ID=<uuid from portal>`
• `CDP_API_KEY_SECRET="-----BEGIN EC PRIVATE KEY-----…"`
• `CDP_WALLET_SECRET=<wallet secret>`
• Chain RPC and vault addresses per target network (Sepolia 84532 or mainnet 8453).

Step 3 — Start local MCP with merge

1. From repo root: `pnpm mcp:dev` (or equivalent mcp-server dev script).
2. Confirm log line: `[forge-mcp] AgentKit tools merged`.
3. Call `tools/list` — expect Forge vault tools plus AgentKit wallet tools.
4. Point Cursor local MCP config at `http://localhost:<port>/mcp` instead of production URL.

Step 4 — cdp-wallet smoke test (optional)

The `cdp-wallet/` package validates CDP credentials independently: create account, request Base Sepolia ETH faucet, send test transaction. Use for deployer ETH top-ups — not vault USDC funding. Vault testnet USDC: Circle faucet on Base Sepolia, not Ethereum L1 Sepolia.

Correct AgentKit + Forge composition

A valid local agent session might: use AgentKit to check CDP wallet ETH balance or send gas; use Forge MCP `simulate_deposit` and `deposit` for vault calldata signed by a different agent EOA holding USDC. Anti-pattern: AgentKit `transfer` USDC into ForgeVault from the CDP-managed wallet — violates custody policy and R4 mitigation #1.

1. Forge MCP: `list_profiles` → confirm conservative live.
2. Forge MCP: `simulate_deposit` for target allocation review.
3. Agent EOA (not CDP): approve USDC + sign deposit calldata.
4. AgentKit (optional): unrelated gas ops on Sepolia test wallet.

Production deploy guardrails

`deploy-mcp-hetzner.sh` removes `CDP_*` environment variables before server upload. Public MCP at `mcp.forgetreasury.com` should never log AgentKit merge. If you see AgentKit tools on production `tools/list`, treat it as a severity-1 misconfiguration — rotate CDP keys and redeploy stripped env. Documented in `docs/MCP_PUBLIC.md` and forge-custody workspace rules.

Field rename reference (AgentKit ≥ 0.10)

Sepolia vs mainnet local configs

Forge MVP testnet is Base Sepolia (84532) — not Ethereum L1 Sepolia. USDC test token: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`. Mainnet Core vault: `0x2C9a3922b426005B979FDD1A8F43Eb61B309193B`. Agents hard-coding wrong chain assets is a common failure mode — encode chain ID in MCP dev env, not agent memory alone.

Troubleshooting

• No AgentKit merge log: CDP vars missing or invalid PEM — check `mcp-server/.env`.
• Tools list only Forge (8–9): Expected on production; locally means CDP not loaded.
• Deposit reverts: Wrong chain, wrong USDC address, or missing approve — not an AgentKit issue.
• Accidental CDP vault deposit: Do not repeat — fund agent EOA instead; CDP is gas-only.

Related guides

MCP-native treasury · Cursor MCP tutorial · LangChain integration · OpenAI Agents SDK. Production path never requires AgentKit.

Frequently asked questions

Can I use AgentKit on Hetzner for convenience?

No — Option A is locked. CTO approval required for Option B, recorded in `docs/MCP_PUBLIC.md`.

Does AgentKit merge change Forge deposit calldata?

No. Forge vault tools behave identically; AgentKit adds parallel wallet tools only.

Is the CDP wallet non-custodial?

CDP API Key Wallets use Coinbase TEE — server credentials authorize operations. That is a different custody model from user EOA signing Forge calldata. Keep scopes operator-only.

Summary

AgentKit merge = local dev convenience for gas and wallet experiments. Production MCP = Forge tools only, no CDP. Vault deposits always from agent EOA via Forge calldata. Deploy script strips CDP vars. Unaudited contracts — Risks.