Skip to main content

MCP Server Integration

The Model Context Protocol (MCP) server lets AI agents interact with your SureStage Sandboxes programmatically. Agents can explore endpoints, inspect state, create routes with validation, and manage Tenant context through a standardized protocol.

What is MCP?​

MCP (Model Context Protocol) is a standard for connecting AI agents to external tools and data sources. SureStage's MCP server exposes Sandbox operations as tools that agents can invoke, enabling AI-assisted API mocking workflows.

How It Works​

The MCP server runs as a stdio transport, meaning it communicates via standard input/output. AI frameworks like Claude Desktop, LangChain, or AutoGPT can connect to the server and invoke tools to:

  • Browse available API endpoints in a Sandbox
  • Inspect Sandbox state and configuration
  • Create new routes with automatic validation
  • Manage Tenant scope for multi-Tenant operations

Setting Up the MCP Server​

Prerequisites​

  • SureStage CLI installed
  • Active Sandbox
  • Authentication token

Start the Server​

surestage mcp start \
  --sandbox-id sandbox_abc123 \
  --token $SURESTAGE_TOKEN

The server starts in stdio mode and waits for tool invocations.

Configure AI Agent​

Add the MCP server to your AI agent's tool configuration:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "surestage": {
      "command": "surestage",
      "args": ["mcp", "start", "--sandbox-id", "sandbox_abc123", "--token", "$SURESTAGE_TOKEN"]
    }
  }
}

LangChain

from langchain.tools import MCPTool

surestage_tool = MCPTool(
    name="surestage",
    command=["surestage", "mcp", "start", "--sandbox-id", "sandbox_abc123", "--token", token]
)

Available Tools​

The MCP server exposes 4 tool groups.

1. Endpoint Explorer​

Browse and search API endpoints defined in the Sandbox.

Tool: endpoint-explorer.list

{
  "action": "list",
  "filters": {
    "method": "GET",
    "path": "/users"
  }
}

Response

{
  "endpoints": [
    {
      "id": "route_123",
      "method": "GET",
      "path": "/users/:id",
      "description": "Retrieve a user by ID"
    },
    {
      "id": "route_456",
      "method": "GET",
      "path": "/users",
      "description": "List all users"
    }
  ]
}

Tool: endpoint-explorer.describe

{
  "action": "describe",
  "routeId": "route_123"
}

Response

{
  "method": "GET",
  "path": "/users/:id",
  "response": {
    "status": 200,
    "body": {
      "id": "{{params.id}}",
      "name": "John Doe"
    }
  },
  "validation": {
    "params": {
      "id": { "type": "string", "required": true }
    }
  }
}

2. Instance Inspector​

Inspect Sandbox state, configuration, and activity.

Tool: instance-inspector.get-state

{
  "action": "get-state",
  "sandboxId": "sandbox_abc123"
}

Response

{
  "state": {
    "cart": [
      { "id": "item1", "quantity": 2 }
    ],
    "userId": "user_789"
  },
  "lastUpdated": "2026-03-21T11:30:00Z"
}

Tool: instance-inspector.get-config

{
  "action": "get-config",
  "sandboxId": "sandbox_abc123"
}

Response

{
  "name": "E-commerce API",
  "baseUrl": "https://sandbox_abc123.surestage.run",
  "routeCount": 42,
  "status": "active"
}

3. Route Builder​

Create new routes with automatic validation and sample value generation.

Tool: route-builder.create

{
  "action": "create",
  "method": "POST",
  "path": "/orders",
  "responseStatus": 201,
  "responseSchema": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string", "format": "uuid" },
      "total": { "type": "number" },
      "status": { "type": "string", "enum": ["pending", "confirmed"] }
    },
    "required": ["orderId", "total", "status"]
  },
  "validation": {
    "body": {
      "items": { "type": "array", "required": true },
      "customerId": { "type": "string", "required": true }
    }
  }
}

The route builder:

  1. Validates the route definition
  2. Generates realistic sample values for the response
  3. Creates the route in the Sandbox
  4. Returns the created route ID

Response

{
  "routeId": "route_789",
  "method": "POST",
  "path": "/orders",
  "sampleResponse": {
    "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "total": 149.99,
    "status": "pending"
  }
}

Tool: route-builder.validate

Validate a route definition without creating it:

{
  "action": "validate",
  "method": "GET",
  "path": "/users/:id",
  "response": {
    "status": 200,
    "body": {
      "id": "{{params.id}}"
    }
  }
}

Response

{
  "valid": true,
  "issues": []
}

4. Tenant Context​

Manage Tenant scope for multi-Tenant operations.

Tool: tenant-context.get-current

{
  "action": "get-current"
}

Response

{
  "tenantId": "tenant_abc123",
  "name": "Acme Corp",
  "tier": "enterprise"
}

Tool: tenant-context.switch

Switch the active Tenant context (requires admin permissions):

{
  "action": "switch",
  "tenantId": "tenant_xyz789"
}

Per-Instance MCP Configuration​

You can customize MCP behavior for each Sandbox using the configuration endpoint.

Get Configuration​

curl https://api.surestage.com/v1/simulations/sandbox_abc123/mcp-config \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "enabledTools": ["endpoint-explorer", "instance-inspector", "route-builder"],
  "routeBuilderDefaults": {
    "generateSamples": true,
    "validateOnCreate": true
  },
  "rateLimits": {
    "requestsPerMinute": 60
  }
}

Update Configuration​

curl -X PATCH https://api.surestage.com/v1/simulations/sandbox_abc123/mcp-config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabledTools": ["endpoint-explorer", "route-builder"],
    "routeBuilderDefaults": {
      "generateSamples": true
    }
  }'

Additional MCP Endpoints​

List Available Prompts​

curl https://api.surestage.com/v1/simulations/sandbox_abc123/mcp-prompts \
  -H "Authorization: Bearer $TOKEN"

Returns pre-configured prompts for common tasks.

List Available Resources​

curl https://api.surestage.com/v1/simulations/sandbox_abc123/mcp-resources \
  -H "Authorization: Bearer $TOKEN"

Returns available data resources the agent can access.

List Available Tools​

curl https://api.surestage.com/v1/simulations/sandbox_abc123/mcp-tools \
  -H "Authorization: Bearer $TOKEN"

Returns the full tool catalog with schemas.

Security​

  • All MCP operations are authenticated via JWT
  • Tenant context is enforced — agents cannot access other Tenants' Sandboxes
  • Tool permissions are scoped to the authenticated user's role
  • Rate limits apply per Sandbox (default: 60 requests/minute)

Common Issues​

Problem: Agent cannot connect to MCP server

Solution: Verify the CLI is installed and the surestage command is in your PATH. Check that the token is valid and not expired.

Problem: Tools not appearing in agent

Solution: Check the enabledTools configuration for the Sandbox. Some tools may be disabled by default.

Problem: Route creation fails with validation error

Solution: Use the route-builder.validate tool to check your route definition before creating it. Ensure all required fields are present.