SMCP Gate API Reference#

Complete reference for all SMCP Gate MCP tools and configuration options.

Base Configuration#

SMCP Gate is accessed via HTTP transport in your MCP client configuration:

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

HTTP Header Configuration#

New in v0.1.0: Pass MCP server configurations via HTTP headers.

X-SMCP-Servers Header#

Configure workspace defaults via the X-SMCP-Servers header:

{
  "mcpServers": {
    "smcp-gate": {
      "transport": {
        "type": "http",
        "url": "https://smcp.apothic.ai/mcp",
        "headers": {
          "X-SMCP-Servers": "<servers><server id='filesystem' transport='stdio' command='npx'><args>-y</args><args>@modelcontextprotocol/server-filesystem</args><args>/workspace</args></server></servers>"
        }
      }
    }
  }
}

Header Format#

Type: XML document encoded into the header value

Schema: A <servers> document containing one or more <server> entries

<servers>
  <server id="filesystem" transport="stdio" command="npx">
    <args>-y</args>
    <args>@modelcontextprotocol/server-filesystem</args>
    <args>/workspace</args>
  </server>
  <server id="github" transport="stdio" command="npx">
    <args>-y</args>
    <args>@modelcontextprotocol/server-github</args>
    <env>
      <GITHUB_TOKEN>ghp_xxx</GITHUB_TOKEN>
    </env>
  </server>
</servers>

Use JSON-style mcpServers arrays in tool-call bodies. Use XML only for the X-SMCP-Servers header.

Precedence Rules#

Body mcpServers overrides header when both are provided
At least one source required: Either header OR body must provide configs
Per-request overrides: Use body to customize for specific requests

| Limit | Value | Reason | |-------|-------|--------| | Max header size | 8KB | Sufficient for ~20-30 MCP servers | | Multiple headers | Rejected | Prevents header smuggling | | Empty/whitespace | Rejected | Invalid configuration | | Invalid XML | Rejected | Clear error message | | Schema validation | Enforced | Zod validation applied |

Error Handling#

Missing Configuration:

{
  "error": "MCP servers configuration required: provide mcpServers in request body or X-SMCP-Servers header"
}

Invalid XML:

{
  "error": "Invalid X-SMCP-Servers header: malformed XML"
}

Schema Validation:

{
  "error": "Invalid X-SMCP-Servers header: [server id is required]"
}

Session Management Tools#

smcp_session_create#

Create a new session with explicit configuration.

Parameters:

{
  mcpServers: Array<{
    id: string;                        // Server identifier
    transport: 'stdio' | 'http' | 'websocket';
    command?: string;                  // For stdio
    args?: string[];                   // Command arguments
    env?: Record<string, string>;      // Environment variables
    endpoint?: string;                 // For http/websocket
  }>;
  ttlMinutes?: number;                 // Session lifetime (1-1440, default: 30)
  exec?: {
    timeoutMs?: number;                // Execution timeout (100-300000, default: 30000)
    memoryMb?: number;                 // Memory limit (16-8192, default: 512)
  };
}

Response:

{
  sessionId: string;                   // Use this for subsequent requests
  port: number;                        // Internal container port
  volumeName: string;                  // Docker volume name
  expiresAt: string;                   // ISO 8601 timestamp
}

Example:

const session = await smcp_session_create({
  mcpServers: [
    {
      id: 'filesystem',
      transport: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/data']
    }
  ],
  ttlMinutes: 120,  // 2 hours
  exec: {
    timeoutMs: 60000,  // 60 seconds
    memoryMb: 1024     // 1GB
  }
});

// Returns:
// {
//   sessionId: "session-abc123xyz",
//   port: 9080,
//   volumeName: "smcp-session-abc123xyz",
//   expiresAt: "2025-10-23T17:35:00Z"
// }

smcp_session_list#

List all active sessions.

Parameters: None

Response:

Array<{
  sessionId: string;
  port: number;
  createdAt: string;                   // ISO 8601 timestamp
  expiresAt: string;                   // ISO 8601 timestamp
}>

Example:

const sessions = await smcp_session_list();

// Returns:
// [
//   {
//     sessionId: "session-abc123",
//     port: 9080,
//     createdAt: "2025-10-23T15:00:00Z",
//     expiresAt: "2025-10-23T15:30:00Z"
//   },
//   {
//     sessionId: "session-xyz789",
//     port: 9081,
//     createdAt: "2025-10-23T15:10:00Z",
//     expiresAt: "2025-10-23T17:10:00Z"
//   }
// ]

smcp_session_status#

Get detailed status for a specific session.

Parameters:

{
  sessionId: string;                   // Session to query
}

Response:

{
  sessionId: string;
  status: 'Running' | 'Stopped' | 'Error';
  uptime: number;                      // Seconds since creation
  port: number;
  createdAt: string;
  expiresAt: string;
  containerInfo: {
    containerId: string;
    image: string;
    status: string;
  };
}

Example:

const status = await smcp_session_status({
  sessionId: "session-abc123"
});

// Returns:
// {
//   sessionId: "session-abc123",
//   status: "Running",
//   uptime: 1800,  // 30 minutes
//   port: 9080,
//   createdAt: "2025-10-23T15:00:00Z",
//   expiresAt: "2025-10-23T15:30:00Z",
//   containerInfo: {
//     containerId: "abc123def456",
//     image: "smcp:latest",
//     status: "running"
//   }
// }

smcp_session_metrics#

Get resource usage metrics for a session.

Parameters:

{
  sessionId: string;                   // Session to query
}

Response:

{
  sessionId: string;
  cpu: {
    usage: number;                     // Percentage (0-100)
    system: number;                    // System CPU seconds
    user: number;                      // User CPU seconds
  };
  memory: {
    usage: number;                     // Bytes
    limit: number;                     // Bytes
    percentage: number;                // Percentage (0-100)
  };
  network: {
    rxBytes: number;                   // Received bytes
    txBytes: number;                   // Transmitted bytes
  };
  uptime: number;                      // Seconds
}

Example:

const metrics = await smcp_session_metrics({
  sessionId: "session-abc123"
});

// Returns:
// {
//   sessionId: "session-abc123",
//   cpu: {
//     usage: 12.5,
//     system: 0.15,
//     user: 0.45
//   },
//   memory: {
//     usage: 134217728,    // 128MB
//     limit: 536870912,    // 512MB
//     percentage: 25.0
//   },
//   network: {
//     rxBytes: 1024000,
//     txBytes: 512000
//   },
//   uptime: 1800
// }

smcp_session_delete#

Delete a session and cleanup all resources.

Parameters:

{
  sessionId: string;                   // Session to delete
}

Response:

{
  sessionId: string;
  deleted: boolean;
  message: string;
}

Example:

await smcp_session_delete({
  sessionId: "session-abc123"
});

// Returns:
// {
//   sessionId: "session-abc123",
//   deleted: true,
//   message: "Session deleted successfully"
// }

Execution Tools#

smcp_execute#

Execute JavaScript code with MCP server access. Automatically creates session if sessionId not provided.

Parameters:

{
  code: string;                        // JavaScript code to execute
  mcpServers?: Array<MCPServer>;       // MCP servers (required if no sessionId/header)
  sessionId?: string;                  // Reuse existing session
  stream?: boolean;                    // Stream output (default: false)
  exec?: {
    timeoutMs?: number;                // Override timeout (100-300000)
    memoryMb?: number;                 // Override memory (16-8192)
  };
}

Response:

{
  sessionId: string;                   // Session used/created
  result: any;                         // Return value from code
  stdout: string;                      // Console output
  stderr: string;                      // Error output
  executionTime: number;               // Milliseconds
}

Example (Auto-Session):

// First request: auto-creates session
const result1 = await smcp_execute({
  code: `
    const fs = mcp.getServer('filesystem');
    const files = await fs.call('list_directory', { path: '/workspace' });
    return files.filter(f => f.endsWith('.json'));
  `,
  mcpServers: [
    {
      id: 'filesystem',
      transport: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace']
    }
  ]
});

// Save sessionId for reuse
const sessionId = result1.sessionId;

// Second request: reuse session
const result2 = await smcp_execute({
  sessionId: sessionId,
  code: `
    const fs = mcp.getServer('filesystem');
    const content = await fs.call('read_file', { path: files[0] }); // Uses files from result1
    return JSON.parse(content);
  `
});

Example (With Header Configuration):

// mcpServers provided via X-SMCP-Servers header
const result = await smcp_execute({
  code: `
    const fs = mcp.getServer('filesystem');
    return await fs.call('list_directory', { path: '/workspace' });
  `
  // No mcpServers needed - uses header
});

Example (Streaming):

const result = await smcp_execute({
  code: `
    console.log('Step 1...');
    await new Promise(resolve => setTimeout(resolve, 1000));
    console.log('Step 2...');
    return 'Done!';
  `,
  mcpServers: [/* ... */],
  stream: true  // Enable streaming
});

// stdout includes timestamped console output

smcp_preview#

Preview MCP server configuration without execution. Automatically creates session if sessionId not provided.

Parameters:

{
  code: string;                        // JavaScript code to preview
  mcpServers?: Array<MCPServer>;       // MCP servers (required if no sessionId/header)
  sessionId?: string;                  // Reuse existing session
}

Response:

{
  sessionId: string;                   // Session used/created
  preview: {
    availableServers: string[];        // Server IDs
    tools: Array<{
      name: string;
      description: string;
      parameters: object;
    }>;
    resources: Array<{
      name: string;
      description: string;
    }>;
  };
}

Example:

const preview = await smcp_preview({
  code: `return mcp.getServer('github').listTools();`,
  mcpServers: [
    {
      id: 'github',
      transport: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-github']
    }
  ]
});

// Returns:
// {
//   sessionId: "session-auto-xyz",
//   preview: {
//     availableServers: ['github'],
//     tools: [
//       { name: 'create_issue', description: 'Create a GitHub issue', ... },
//       { name: 'list_repositories', description: 'List repositories', ... }
//     ]
//   }
// }

MCP Code API#

Inside executed code, use the global mcp object to interact with MCP servers:

mcp.getServer(id)#

Get a reference to an MCP server.

const fs = mcp.getServer('filesystem');
const github = mcp.getServer('github');

server.call(tool, params)#

Call an MCP tool.

const files = await fs.call('list_directory', {
  path: '/workspace'
});

const issue = await github.call('create_issue', {
  repo: 'owner/repo',
  title: 'Bug Report',
  body: 'Description here'
});

server.listTools()#

List available tools from the server.

const tools = await fs.listTools();
// Returns: [{ name: 'list_directory', description: '...', ... }, ...]

server.listResources()#

List available resources from the server.

const resources = await fs.listResources();
// Returns: [{ name: 'file', description: '...', ... }, ...]

Configuration Options#

Environment variables for deployment:

| Variable | Default | Range | Description | |----------|---------|-------|-------------| | SMCP_GATE_PORT | 3000 | 1-65535 | HTTP server port | | SMCP_SESSION_TTL_MINUTES | 30 | 1-1440 | Default session lifetime | | SMCP_CLEANUP_INTERVAL_MINUTES | 5 | 1-60 | Cleanup job frequency | | SMCP_MAX_SESSIONS | 100 | 1-1000 | Max concurrent sessions | | SMCP_CONTAINER_PORT_MIN | 9080 | 1024-65535 | Min container port | | SMCP_CONTAINER_PORT_MAX | 9180 | 1024-65535 | Max container port | | SMCP_DEFAULT_TIMEOUT_MS | 30000 | 100-300000 | Default execution timeout | | SMCP_DEFAULT_MEMORY_MB | 512 | 16-8192 | Default memory limit |

Error Handling#

All tools return errors with consistent structure:

{
  error: string;                       // Error type/code
  message: string;                     // Human-readable message
  details?: object;                    // Additional context
  statusCode?: number;                 // HTTP-style status code
}

Common Errors#

Missing Configuration:

{
  "error": "MCP servers configuration required",
  "message": "provide mcpServers in request body or X-SMCP-Servers header",
  "statusCode": 400
}

Session Not Found:

{
  "error": "Session not found",
  "message": "Session 'session-abc123' does not exist or has expired",
  "statusCode": 404
}

Execution Timeout:

{
  "error": "Execution timeout",
  "message": "Code execution exceeded timeout of 30000ms",
  "statusCode": 408
}

Resource Limit Exceeded:

{
  "error": "Memory limit exceeded",
  "message": "Execution exceeded memory limit of 512MB",
  "statusCode": 507
}

Rate Limiting#

SMCP Gate enforces per-client rate limits:

Default: 100 requests per minute
Burst: 20 requests per second

Rate limit headers in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1634567890

Health Endpoints#

GET /health#

Basic health check.

Response:

{
  "status": "ok",
  "uptime": 3600,
  "sessionCount": 45,
  "timestamp": "2025-10-23T15:35:00Z"
}

GET /ready#

Readiness probe (checks Docker connectivity).

Response:

{
  "ready": true,
  "dockerConnected": true,
  "activeSessions": 45,
  "availablePorts": 55
}

Next Steps#

Session Management Guide - Advanced session patterns
Security Best Practices - Production deployment
Examples & Recipes - Common use cases