MCP Management in Cloud

MCP servers extend containers with domain-specific capabilities. The Cloud API lets you attach, inspect, and remove servers without rebuilding images.

Concepts

• Hosted servers — Accessible over HTTP/SSE. You supply URLs and optional auth tokens. Ideal for SaaS integrations (Notion, GitHub, internal APIs).
• Local servers — Run inside the container using stdio. The Cloud API installs npm packages and launches them with your chosen command/args.
• Tool availability — Agents discover MCP tools automatically; no manual prompt engineering required.

Add a hosted server

POST /api/v1/containers/:id/mcp-servers
Authorization: Bearer tb_prod_xxx
Content-Type: application/json
 
{
  "server": {
    "type": "hosted",
    "name": "notion",
    "url": "https://notion-mcp.example.com/mcp",
    "bearerToken": "notion-secret",
    "headers": {
      "X-Custom": "value"
    },
    "startupTimeoutSec": 30,
    "toolTimeoutSec": 60
  }
}

Hosted servers don’t require package installation. The Cloud API stores credentials encrypted and injects them when the agent connects.

Add a local server

POST /api/v1/containers/:id/mcp-servers
 
{
  "server": {
    "type": "local",
    "name": "filesystem",
    "package": "@modelcontextprotocol/server-filesystem",
    "command": "npx",
    "args": ["@modelcontextprotocol/server-filesystem", "/workspace"],
    "env": { "TZ": "UTC" },
    "startupTimeoutSec": 45
  }
}

Local servers pull npm packages into the container (using npm install) before launching the command. Keep your container network egress open to npm or host packages internally.

Review and remove

GET /api/v1/containers/:id/mcp-servers
DELETE /api/v1/containers/:id/mcp-servers/:name

list returns the canonical JSON definition for each server, making it easy to recreate the same configuration elsewhere.

Cloud SDK helpers

const cloud = new TestbaseCloud({ apiKey: process.env.TESTBASE_API_KEY });
const agent = await cloud.createCloudAgent({ name: 'Worker', agentType: 'worker', workspace: './repo' });
 
await cloud.addMcpServer(agent.containerId, {
  type: 'hosted',
  name: 'github',
  url: process.env.GITHUB_MCP_URL!,
  bearerToken: process.env.GITHUB_TOKEN
});
 
const servers = await cloud.listMcpServers(agent.containerId);
await cloud.removeMcpServer(agent.containerId, 'github');

Best practices

• Namespace servers: choose descriptive names (github-readonly, jira-write) so tool invocations remain clear.
• Rotate credentials: update hosted server tokens through remove + add so new credentials propagate without downtime.
• Observe startup logs: if a server fails to boot, container logs include the stdout/stderr from the command—grab them via cloud.getLogs.
• Limit privileges: hosted MCP servers accept allowedTools lists. Restrict agents to the minimal toolset they need.
• Package caching: persistent containers only install npm packages once. Ephemeral containers reinstall on each creation—consider prebuilding custom images if you rely on large packages.

Managing MCP centrally keeps your agents modular—focus on business logic while the platform handles tool lifecycle.