SMCP Quick Start - Apothic AI Documentation

SMCP Gateway provides Scriptable MCP (SMCP) in local and hosted sandbox sessions. Each session runs in its own isolated container with independent MCP server configurations and resource limits.

Prerequisites#

Before using SMCP Gate, you need:

An MCP client (Claude Desktop, Claude Code, or custom client)
A free Apothic AI account

MCP servers can be specified at inference-time by your LLM agent, by you via HTTP headers in your agent's MCP configuration, in .smcp.toml files (For your local MCPs), or any combination of the aforementioned methods.

The SMCP Gateway#

First, configure your MCP client to connect to the Apothic SMCP Gateway:

{
  "mcpServers": {
    "smcp": {
      "type": "http",
      "url": "https://smcp.apothic.ai/mcp"
    }
  }
}

While not a requirement, you can also add your MCP servers as HTTP headers in your agent's MCP config.

For example, you might include the exa MCP server:

{
  "mcpServers": {
    "smcp": {
      "type": "http",
      "url": "https://smcp.apothic.ai/mcp",
      "headers": {
        "X-SMCP-Servers": "<servers><server id='exa' transport='stdio' command='npx'><args>-y</args><args>exa-mcp-server</args><env><EXA_API_KEY>your-api-key-here</EXA_API_KEY></env></server></servers>"
      }
    }
  }
}

We use XML format for the X-SMCP-Servers header to allow complex nested configurations while maintaining readability. With formatting applied, it looks like this:

<servers>
  <server id="exa" transport="stdio" command="npx">
    <args>-y</args>
    <args>exa-mcp-server</args>
    <env>
      <EXA_API_KEY>your-api-key-here</EXA_API_KEY>
    </env>
  </server>
</servers>

or you can simply import MCP servers from your existing config files.

MCP import examples:

# import all supported MCP configs from a directory
npx @apothic-ai/smcp import /path/to/subdir # (omit path for cwd)

# import your MCP servers from Github Copilot
npx @apothic-ai/smcp import /path/to/.mcp.json

# import your MCP servers from Claude Code
npx @apothic-ai/smcp import /path/to/.claude.json

SMCP supports importing MCP configs from the following apps:

Claude Code
Claude Desktop
Codex
Github Copilot
Google CLI
Cline & RooCode

Local MCPs#

While you can run all your MCPs inside hosted Apothic sandboxes, you can also run them locally. This is important for MCPs which require access to resources on your local machine.

Start the MCP->SMCP Bridge:

npx @apothic-ai/smcp
# You will be prompted to sign-in on the first run

Initialize a new .smcp.toml:

# smcp will hot-reload .smcp.toml from the cwd and parent directories
npx @apothic-ai/smcp init

.smcp.toml Local MCP example:

[mcp_servers.hyperglyph]
command = "npx"
args = ["-y", "@apothic-ai/hyperglyph"]

[mcp_servers.hyperglyph.env]
HYPERGLYPH_PROJECTS = "/home/user/src/my-python-project,/home/user/src/my-js-project"

Dynamic MCPs At Inference#

During inference, your agent can specify MCP servers dynamically by including them in the mcpServers field of an smcp_execute tool call.

Any MCP servers your agent already knows about (From training or in-context) can be used. If you intend to utilize this feature, you may want to provide your agent with example MCP server definitions in its prompt or system instructions.

Example System Prompt#