Connect a remote MCP server

If your tools already exist behind an MCP endpoint, yours or a vendor’s, connect the server instead of rebuilding them as a tool package. Caplo calls the server over HTTPS with a credential you configure, and only for the tools you review and publish.

How it works

• Workspace credential. Caplo stores one credential per server and uses it for every conversation in the workspace. Agents can reach anything that credential can, so give it the narrowest access that works.
• Review before use. Caplo lists the server’s tools, but none reaches an agent until you enable it, classify it as read or write, and publish. Write tools ask the customer to confirm by default, as with tool packages.
• Pinned contracts. Publishing creates a numbered version that pins each enabled tool’s description and schemas. Agents pin that version when you publish them.
• Change detection. Caplo checks each server about every 15 minutes. If a published tool’s schema changes or the tool disappears, the server shows Tools changed and Caplo stops calling the changed tools until you review the new list and publish again.
• Idempotency. Calls to write tools carry the action’s idempotency key in the request’s _meta as io.caplo/idempotencyKey, so your server can apply each confirmed write once.
• Network. Calls leave through Caplo’s egress. Servers on private, loopback or link-local addresses are not reachable. Responses must be under 256 KiB, and each tool has a timeout of 1 to 30 seconds (20 by default).

The server’s name is permanent, unique among the workspace’s packages and servers, and prefixes its tools: a search tool on server crm is crm/search in agent YAML and crm__search to the model.

Authentication

Method	CLI --auth	Use it when
No auth	none	The server is public.
Bearer token	bearer	The server takes a static token as Authorization: Bearer.
Custom header	header	The server takes an API key in a header you name, such as X-API-Key.
OAuth, a user signs in	oauth (grant authorization_code)	The server uses OAuth with PKCE. A workspace member signs in once; Caplo stores and refreshes the token.
OAuth, the client itself	oauth --oauth-grant client_credentials	Machine-to-machine OAuth with a confidential client and its secret.

For OAuth, Caplo registers itself with the authorization server where the server allows it. Otherwise use a client an administrator registered: pass its client ID and secret, and add Caplo’s redirect URI (shown in the console, or by caplo mcp get) to the client’s allowed redirect URIs.

Tokens, header values and client secrets are write-only. Caplo stores them encrypted and never shows them again.

Connect, review and publish

Console

1. Open Tools, select Add tools, then Connect MCP server.

2. Server. Enter the Server URL, for example https://mcp.example.com/mcp, and select Check server. Caplo reports whether the endpoint speaks MCP, how many tools it lists, and whether it asks for OAuth. Checking saves nothing. Leave Transport on Detect automatically unless you know the server only speaks one. Select Continue.

3. Connection. Enter a Display name and a Name (lowercase, permanent), then choose the Authentication method:

   • Bearer token or Custom header: paste the value.
   • OAuth: under Who signs in, choose A user signs in or The client itself. Choose Register automatically, or Use a registered client and enter its Client ID and, for a confidential client, its Client secret. Copy the Redirect URI into a registered client’s settings.

   Select Save server, or Save and authorize for OAuth, which sends you to the authorization server to sign in.

4. Tools. Caplo shows how many tools it discovered. Select Review tools.

5. In the review, enable each tool agents may use and set its Effect (Read only or Writes data), its Confirmation for writes (Customer confirms or No confirmation) and its Timeout. Select Save review, then the publish button, which names how many tools it publishes, such as Publish 2 tools.

The server’s section on the Tools page shows its status, authentication and how many tools are published, with Connect or Reconnect (OAuth), Review tools (or Review changes), Check now, Edit and Remove.

CLI

1. Check the server. Nothing is saved. Add --bearer-stdin, or --header X-API-Key --value-stdin, to check with a credential.

   caplo mcp check https://mcp.example.com/mcp

2. Add it. Give it a name and the authentication method. Secrets are read from standard input (a hidden prompt on a terminal) or from an environment variable, never from a flag value.

   # OAuth, a user signs in; Caplo registers itself where the server allows it
   caplo mcp add crm --url https://mcp.example.com/mcp --auth oauth --display-name "Customer CRM"
   
   # OAuth with a registered confidential client
   caplo mcp add crm --url https://mcp.example.com/mcp --auth oauth --client-id caplo --client-secret-stdin
   
   # OAuth, client credentials
   caplo mcp add crm --url https://mcp.example.com/mcp --auth oauth --oauth-grant client_credentials --client-id caplo --client-secret-env CRM_CLIENT_SECRET
   
   # A static token, or an API key header
   caplo mcp add crm --url https://mcp.example.com/mcp --auth bearer --secret-stdin
   caplo mcp add crm --url https://mcp.example.com/mcp --auth header --header-name X-API-Key --secret-env CRM_API_KEY

   Use --scope (repeatable) to request specific OAuth scopes and --token-auth-method if the token endpoint needs client_secret_basic or client_secret_post.

3. Authorize (OAuth). Open the printed URL in a browser signed in to the Caplo console; the console completes the authorization. --open opens it for you. The client credentials grant completes at once.

   caplo mcp connect crm --open

4. Review the tools. List them, then enable and classify the ones agents may use, by their remote name:

   caplo mcp tools crm
   caplo mcp review crm \
     --enable search_contacts=read \
     --enable create_note=write \
     --confirmation create_note=required \
     --timeout search_contacts=10

   --enable without =read or =write keeps the tool’s current effect or takes the one the server’s readOnlyHint suggests. Check it: hints are only suggestions. Tools you do not name keep their review; --disable turns one off.

5. Publish.

   caplo mcp publish crm

   Published crm version 1 with 2 tools
   ...
   Agent files use them as crm/<tool>

Command	Use
caplo mcp list, caplo mcp get <name>	Status, authentication, last error, OAuth redirect URI and discovered tools.
caplo mcp refresh <name>	Check the server now and refresh its tool list.
caplo mcp update <name>	Change the URL, transport or credential. A new URL or authentication discards stored OAuth tokens, so run caplo mcp connect again.
caplo mcp remove <name>	Remove the server. Its published tools stop working and its credentials are deleted.

See the caplo mcp reference.

Then select the tools on an agent and publish the agent. See Give an agent tools.

Statuses

Status	Meaning and fix
Connected	Working.
Needs authorization	OAuth was never completed, a token was rejected or could not be refreshed, or the server needs more scopes. Select Connect or Reconnect, or run caplo mcp connect.
Degraded	A server that worked before is timing out or failing. Caplo keeps checking.
Tools changed	A published tool changed or disappeared on the server. The changed tools are blocked until you review the list and publish again.
Error	The endpoint is not an MCP server, is unreachable, or refused the destination. Fix it with Edit or caplo mcp update, then check again.

Caution

Remove deletes the server’s credentials and stops its published tools in every agent that uses them. To pause a single agent’s use, remove the tools from that agent and publish it instead.

Let an AI agent do it

AI prompt

Connect a remote MCP server to Caplo

Checks an MCP server, adds it to the workspace with the right authentication, reviews its tools and prepares them for publishing.

Copy promptOpen in ClaudeOpen in ChatGPT

Show prompt

Goal: connect the remote MCP server at `<SERVER_URL>` to my Caplo workspace as `<SERVER_NAME>` (lowercase letters, digits and dashes; permanent), review its tools so only the ones I want are enabled with the correct effect, and publish them once I approve.

Read these pages first:

- https://docs.caplo.si/tools/remote-mcp.md
- https://docs.caplo.si/tools/write-tools.md
- https://docs.caplo.si/agents/tools.md

Steps:

1. Confirm the CLI is signed in to the right workspace with `caplo auth status`.
2. Check the server without saving anything:

   ```sh
   caplo mcp check <SERVER_URL>
   ```

   Report whether it is reachable, its protocol and transport, how many tools it lists, and whether it requires OAuth. If it requires a token or API key header, ask me which.
3. Add it with the authentication the check suggests. Read any secret from standard input or an environment variable that I set; never ask me to paste it into this chat.

   ```sh
   # OAuth where a person signs in
   caplo mcp add <SERVER_NAME> --url <SERVER_URL> --auth oauth
   # or a static token / API key header, read from an environment variable I export myself
   caplo mcp add <SERVER_NAME> --url <SERVER_URL> --auth bearer --secret-env <TOKEN_ENV_VAR>
   caplo mcp add <SERVER_NAME> --url <SERVER_URL> --auth header --header-name <HEADER_NAME> --secret-env <TOKEN_ENV_VAR>
   ```

   If the authorization server refuses automatic client registration, tell me; I will create a client and give you its ID, and run `caplo mcp get <SERVER_NAME>` to show me the redirect URI to register.
4. For OAuth with a person signing in, run `caplo mcp connect <SERVER_NAME>` and tell me to open the printed URL in a browser where I am signed in to the Caplo console. Wait for it to finish.
5. List the tools with `caplo mcp tools <SERVER_NAME>`. Propose which to enable, each with an effect: `read` only if it cannot change anything; `write` for anything that creates, updates, deletes, sends or charges. Do not trust the server's `readOnlyHint` alone; read each description and schema. Propose a timeout (1 to 30 seconds) where the default of 20 does not fit. Show me the proposal and wait.
6. Apply the review I approve, for example:

   ```sh
   caplo mcp review <SERVER_NAME> --enable <READ_TOOL>=read --enable <WRITE_TOOL>=write --confirmation <WRITE_TOOL>=required --timeout <READ_TOOL>=10
   ```

7. Ask me before publishing. When I approve, run `caplo mcp publish <SERVER_NAME>` and tell me the agent YAML names it prints (`<SERVER_NAME>/<tool>`).

Verify: `caplo mcp get <SERVER_NAME>` shows status `connected`, a published version, and only the tools I approved enabled.

Rules:

- Never print, log or store a token, header value or client secret, and never put one in a command line argument, file or this chat.
- Keep `confirmation` required for every write tool unless I explicitly ask otherwise.
- Do not run `caplo mcp publish`, `caplo mcp remove` or `caplo mcp update` without my approval.
- Remember that the credential is shared by every conversation in the workspace; point out if the server's credential has broader access than these tools need.