MCP Servers¶

Model Context Protocol (MCP) servers let an Agent connect to external tools, data sources, and internal systems. Within its authorization scope, the Agent can query data, invoke tools, access system capabilities, or perform specific operations.

Unlike a Skill, an MCP service is closer to a tool gateway. Services that connect to production systems, customer data, or write-capable APIs require particular attention to permissions, data scope, and operational risk.

If you are not sure whether to use a Skill, an MCP server, or both, start with Skills and MCP: How to Choose.

Configuration Model¶

Toby AI Agents uses a "configure globally, enable per Agent, verify at runtime" model:

flowchart LR
  A[Configure a global MCP service] --> B[Enable it for an Agent]
  B --> C[Agent runtime installs and activates it]
  C --> D[Inspect actual tools]
  D --> E[Use them in a task]

Global configuration determines which services are available in the workspace; it does not expose them to every Agent automatically. A switch in an Agent workspace affects that Agent only.

Before You Start¶

Make sure that:

• The MCP Server comes from a trusted source and provides configuration suitable for the runtime environment;
• The target Agent host can reach the MCP Server, package registry, and related business systems;
• A local stdio service has the required Node.js, Python, or other runtime dependencies;
• A remote HTTP service has the required network, proxy, certificate, and authentication setup;
• Your account can manage global MCP services and the target Agent;
• The data scope and possible write operations exposed by the tools are understood.

Step 1: Manage Global MCP Servers¶

Select your avatar and open Agent Configuration > MCP Servers in Settings. This workspace-level capability pool lets administrators add, search, edit, or remove services and inspect available tool information. Whether a service is enabled for a particular Agent is controlled from that Agent's workspace.

Add a Service¶

1. Click Add MCP.
2. Copy the configuration JSON from the MCP Server's official documentation or another trusted source.
3. Paste it into the editor and review the name, transport, command, or endpoint.
4. Save the configuration.
5. Review preparation status, connection errors, and discoverable tools on the service card.

The configuration uses an mcpServers object and must contain exactly one service. Common fields are:

stdio example:

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "mcp-server-example"],
      "package_name": "mcp-server-example",
      "transport": "stdio"
    }
  }
}

Remote HTTP example:

{
  "mcpServers": {
    "internal-readonly": {
      "transport": "http",
      "url": "https://mcp.example.com/server"
    }
  }
}

Follow the fields documented by the MCP Server provider. Do not guess commands, arguments, or endpoints to make a configuration pass validation. Use team-approved secret management and runtime injection instead of placing long-lived credentials in configuration visible to many users.

Inspect Status and Tools¶

A global service card can show configuration, preparation or connection state, and tools when discovery is supported. Depending on the service, you can:

• Expand the tool list to review names and descriptions;
• Inspect connection errors and retry;
• Edit configuration;
• Remove the service.

A remote HTTP service can expose connection and discovery status directly. A local stdio service ultimately runs in the Agent environment, so use the runtime status and tool list in the Agent workspace as the source of truth after enabling it.

Step 2: Enable the Server for an Agent¶

A globally configured service is not enabled for every Agent:

1. Open the target Agent workspace.
2. Go to Configuration > MCP Servers.
3. Find the service and turn on its switch.
4. Wait for the resource to be saved, installed, and activated.
5. Expand runtime tools and confirm that the count, names, and descriptions are as expected.

Search matches the MCP server name, runtime tool name, and tool description, so you can locate a server from the capability you need.

Each switch action saves only that MCP service; it does not resubmit or lock every MCP configuration for the Agent. While the current service is saving, installing, waiting, or being removed, its switch is temporarily locked. Other services remain independent.

Enable services according to Agent responsibility and least privilege. A production troubleshooting Agent may need read-only query services; a cloud cost Agent may need billing services; a document organization Agent should not receive production tools.

Understand Runtime Status¶

The Agent workspace follows configuration from save through runtime availability:

The runtime tool section is collapsed by default. Its header shows the count actually reported by Agent runtime. Expand it to inspect components, transports, tool names, and descriptions. Disabling a service immediately hides its tools from the current availability list.

When a new configuration fails but a previous version is still serving tools, the page displays an explicit warning. Do not treat the new configuration as active until the error is fixed and reinstallation completes.

Step 3: Use MCP Tools in a Task¶

After activation, the Agent can select an MCP tool based on the task goal. You can also state which objects to query, which capability to use, and what output to return.

Start with a low-risk test:

Use the enabled read-only Kubernetes MCP service to list the five Pods with the most restarts in the test namespace.
Read data only. Return the object name, restart count, and recommended checks.

For production environments, customer data, permission changes, or write operations, define the exact scope, expected result, and actions requiring approval. Confirm that the Agent's access scope and behavioral boundaries match the task.

Troubleshoot MCP Servers¶

Recommendations¶

• Enable only the MCP services directly related to the Agent's responsibility;
• Prefer read-only or least-privilege credentials and restrict data and action scope in the target system;
• Copy configuration from trusted sources and review package versions before upgrades;
• Keep human approval for production writes and state prohibited actions in Agent behavioral boundaries;
• After a change, verify activation from runtime status and the actual tool list;
• Review failed, disabled, and unused services regularly and repair or remove them;
• When a required service is unavailable, require the Agent to state the missing capability instead of drawing a definite conclusion from incomplete data.