Skip to main content

​
Outcome

The agent’s harness lists the MCP server’s tools at session start, the token is injected from a connection at launch, and the template snapshot contains the server definition but no secret.

​
Before you start

  • You are an admin with an org-scoped API key.
  • The MCP server runs as a local command. The official Stripe server, npx -y @stripe/mcp --tools=all, is used below; it reads STRIPE_SECRET_KEY from the environment.
  • The agent’s template exists and builds successfully.

​
Do it

1

Define the server without the secret

In Settings > Context > Tools & MCP click New tool or MCP server and choose MCP server. Give it the command and arguments only. Do not add the key as an environment variable here; anything in the directive is written verbatim into the snapshot.
2

Add a connection for the token

Open the new server and add a connection of kind env with STRIPE_SECRET_KEY set to a restricted read-only key. Choose the scope: org-wide for everyone, personal for yourself, or agent for one roster agent. Connections are created in the dashboard or through POST /api/cloud/agent-directives/{id}/connections; the CLI does not create them.
3

Attach it to the template

Attach the server to the agent’s template. Like a skill, an MCP server applies to nothing until it is attached.
4

Rebuild

The server definition lands in the snapshot at build time. The connection is resolved at each session start, so rotating the token later needs no rebuild.

​
Verify

Start a session from the template and ask the harness what tools it has. In Claude Code, /mcp lists connected servers and their tools; a prompt such as “list the Stripe MCP tools you can call” also works. If the server appears but every call fails with an authentication error, the connection is missing or has the wrong scope for this run.

​
Gotchas

  • Secret in the directive. An --env STRIPE_SECRET_KEY=... on the server definition bakes the key into every snapshot and shows it to anyone who can read the directive. Use a connection.
  • Attached, not built. The server is attached but attachments_changed_since_build is true. Sessions still boot the old snapshot until you build.
  • Scope mismatch. A personal connection is used only for runs whose effective user is you. An agent run by someone else falls to the agent connection or the org-wide one, and if neither exists the server starts unauthenticated.
  • Provider or MCP server, not both. If the same template also has a Stripe tool provider, the agent has two ways to reach Stripe. Pick the one the runbook uses.

3. Give it tools

When to choose an MCP server over a tool provider, and how connections are scoped.