MCP Servers

Crafting provides a centrally managed mechanism to advertise MCP (Model Context Protocol) servers to all sandboxes in an org. Rather than configuring MCP servers in each sandbox individually, they can be registered once at the org level and automatically become available everywhere.

Adding an MCP Server

To make an MCP server globally available to all sandboxes in the org:

1. Create a Pinned sandbox running the MCP server, ensuring:
2. The listening port is exposed as an INTERNAL endpoint with auth_proxy disabled. (See Endpoints.)

3. The sandbox definition includes the MCP server declaration:

   yaml customizations: - mcp_server: endpoint: ENDPOINT-NAME

   Where ENDPOINT-NAME is the name of the internal endpoint exposing the MCP server.

4. Authorize the MCP server as an org admin:

5. Visit Connect / LLM in the Web Console.
6. Go to the Discovery tab.
7. Authorize the MCP server sandbox.

External MCP Servers

In the Discovery tab of Connect / LLM, external MCP servers can be defined directly by providing the server URL and optional authentication information. Once added, they become available to all sandboxes without requiring a dedicated pinned sandbox.

Using MCP Servers

Once authorized, the MCP configuration is available in all workspaces:

These configuration files can be loaded by any agent or MCP-compatible client running inside the workspace.

Inside a workspace, local MCP servers can also be configured using:

• /etc/sandbox.d/mcp.json
• ~/.sandbox/mcp.json

For the built-in coding CLI commands (cs claude, cs gemini, cs codex), both MCP configuration files are loaded automatically. No additional setup is required.

Authentication

By default, no authentication is performed against MCP servers. If authentication is required, an auth block can be added to the MCP server definition:

customizations:
- mcp_server:
    endpoint: ENDPOINT1
    auth:
      token:
        secret:
          name: SECRET-NAME
- mcp_server:
    endpoint: ENDPOINT2
    auth:
      token:
        login:
          name: LOGIN-PROVIDER-NAME

• If secret is specified, the token is retrieved from the named Secret.
• If login is specified, the token is retrieved from the owner's access token for the named Login Provider. The owner must have previously logged in to that provider; otherwise authentication will fail.

Authentication token injection only applies to:

• Globally registered MCP servers (in the Discovery tab of Connect / LLM).
• Workspaces accessing MCP servers through the gateway proxy (DNS names with the .g.sandbox suffix).

It does not apply to local MCP server configurations or direct access to internal endpoints.

Custom Header and Token Type

By default, the access token is injected as Authorization: Bearer TOKEN. This can be overridden by specifying a custom header or token type:

customizations:
- mcp_server:
    endpoint: ENDPOINT1
    auth:
      token:
        header: X-Auth
        type: ApiKey
        secret:
          name: api-key

This injects X-Auth: ApiKey SECRET.

Default behaviour rules:

• If header is not specified, type defaults to Bearer, producing Authorization: Bearer TOKEN.
• If header is specified but type is not, there is no type prefix — only the raw secret value is used.

Examples:

# Injects: Authorization: Basic SECRET
customizations:
- mcp_server:
    endpoint: ENDPOINT1
    auth:
      token:
        type: Basic
        secret:
          name: api-auth

# Injects: X-Api-Key: SECRET  (no type prefix)
customizations:
- mcp_server:
    endpoint: ENDPOINT1
    auth:
      token:
        header: X-Api-Key
        secret:
          name: api-key

See Also

• LLM Config — configuring LLM providers and authorizing MCP servers
• Login Provider and Access Tokens — per-user access tokens for MCP server authentication
• Agentic Sessions — sessions that use MCP tools
• Endpoints — exposing the MCP server as an internal endpoint
• Auto Suspension — the Pinned sandbox running MCP servers should be pinned to avoid suspension