MCP Servers

Crafting provides a centrally managed mechanism to seamlessly advertise MCP (Model Context Protocol) servers to all sandboxes. An MCP server can be defined as an external URL, or by using the internal endpoint of a Pinned sandbox that is specially annotated as an MCP endpoint.

Setup Organizational MCP Servers

Organizational MCP servers are configured in the Discovery tab of the AI/LLM setup page — Connect / LLM from the Full Web Console, or Setup / AI from the Agentic UI.

The Authorized MCP Servers list contains the MCP servers shared across the org. They are automatically proxied in all sandboxes using a special URL of the form http://NAME.mcp.llm.g.sandbox, where NAME is the name of the MCP server in the list. They are, however, not included in /run/sandbox/fs/metadata/mcp.json inside the sandboxes.

To include an MCP server in the mcp.json file of the metadata filesystem, add or reference the MCP server in the Globally Activated MCP Servers list.

By default, arbitrary MCP servers are not allowed. Only the servers in the Authorized MCP Servers list can be referenced in:

AI Agents
the Globally Activated MCP Servers list

To allow other MCP servers to be added to the Globally Activated MCP Servers list (admin only), or to be defined in AI agents, turn on Allow custom MCP servers.

With that turned on, specific MCP servers can be added to the Blocked MCP Servers list so that they are never used, regardless of where they are defined.

Authentication

Crafting supports shared secrets or per-user logins for MCP server authentication.

When adding an MCP server, Authentication can be turned on, selecting whether to use a Secret or an existing Login Provider. If a Login Provider is used, every member in the org must log in to that Login Provider before the MCP server can be accessed successfully.

MCP Server from a Sandbox

A running sandbox — recommended to be Pinned — can serve as an MCP server too, by annotating an internal endpoint as an MCP endpoint.

Annotate MCP Endpoint

Add the following customization to the sandbox definition (or to the template, and sync it to the sandbox):

customizations:
- mcp_server:
    endpoint: ENDPOINT-NAME

Where ENDPOINT-NAME must refer to the name of an internal HTTP endpoint.

By default, no authentication is performed against MCP servers in sandboxes. If authentication is required, an additional auth block can be specified:

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 specified Secret. The personal secret is used if present; otherwise the shared secret in the org is used.
If login is specified, the token is retrieved from the owner's access token of the specified Login Provider. This requires the owner to have logged in to that Login Provider; otherwise authentication will fail.

Custom Header and Token Type

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

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

This injects the header X-Auth: ApiKey SECRET.

Note: if header is unspecified, the default value of type is Bearer. If header is specified, there is no default value for type; when unspecified, it is empty. For example:

customizations:
- mcp_server:
    endpoint: ENDPOINT1
    auth:
      token:
        type: Basic
        secret:
          name: api-auth

This injects the header Authorization: Basic SECRET.

customizations:
- mcp_server:
    endpoint: ENDPOINT1
    auth:
      token:
        header: X-Api-Key
        secret:
          name: api-key

This injects the header X-Api-Key: SECRET (no type, as there is no default).

Use the MCP Servers in Sandboxes

For Crafting agents, and CLI extensions such as cs claude, the MCP servers defined in the following locations are loaded automatically:

/opt/sandboxd/etc/mcp.json
/etc/sandbox.d/mcp.json (if present)
~/.sandbox/mcp.json (if present)
/run/sandbox/fs/metadata/mcp.json, containing the entries from Globally Activated MCP Servers

Specific to Crafting agents, /opt/sandboxd/etc/mcp.json may be skipped if the Crafting system tools are not desired.