MCP Servers

MCP (Model Context Protocol) is an open standard for connecting AI agents to tools and data sources. By integrating an MCP server into Agent Studio, you can extend the Tyrell Agent with custom capabilities — from accessing external APIs to connecting internal systems.

For a general overview of MCP configurations in the platform, see MCP Configs.

Overview

MCP servers expose tools that the Agent discovers and calls automatically. Once configured, the Agent sees your MCP server's tools alongside its built-in capabilities and attached services.

The communication flow:

The server starts, the Agent discovers the available tools and their schemas.
When a tool is relevant, the Agent sends a request with the appropriate parameters.
The MCP server executes the logic and returns a response.
The Agent incorporates the response into its work.

Building an MCP server

The official MCP documentation provides comprehensive guides for building MCP servers in multiple languages:

Follow the official guide to build your server, then return here to integrate it with Agent Studio.

ℹ Tip

When building tools for Agent Studio, return markdown-formatted strings and write clear docstrings — the Tyrell Agent reads these to understand when and how to use each tool.

Integrating with Agent Studio

Step 1: Place your server on the server

Your MCP server code must be accessible from the Agent Studio server where it will run. Common locations include:

In a volume — Place your server in a workspace volume at /workspace/volumes/<volume-name>/ so it persists across server restarts and can be shared.
In the workspace — Place it in /workspace/ on the server for quick iteration during development.
Installed globally — Install your server as a package (e.g., via pip install or npm install -g) so it's available system-wide.

Step 2: Configure the MCP server

Navigate to the MCP Configs page and add a new configuration. The configuration is a JSON object that tells the platform how to start your MCP server:

json

{
  "mcpServers": {
    "my-custom-server": {
      "command": "python",
      "args": ["/workspace/volumes/my-volume/mcp-server/server.py"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Each MCP config entry defines a single server. To add multiple MCP servers, create a separate config for each one — the platform combines them automatically at runtime.

Configuration fields

Field	Description
`command`	The command to start the server (e.g., `python`, `node`, `npx`).
`args`	Arguments passed to the command — typically the path to your server script.
`env`	Environment variables to set. Use `${SECRET_NAME}` syntax to inject Secrets.

Step 3: Choose the scope

When creating the MCP config, select the appropriate scope:

Scope	Visibility	Default state	Best for
Organization	All workspaces in the Organization	Disabled per workspace	Shared infrastructure tools
User	Your workspaces only	Enabled	Personal productivity tools
Workspace	Single workspace	Enabled	Project-specific integrations

Organization-level configs must be explicitly enabled per workspace. User and Workspace configs are enabled by default.

Step 4: Use secrets for credentials

If your MCP server needs API keys or credentials, store them as Secrets rather than hardcoding them in the configuration:

Add the secret on the Settings > Secrets page.
Reference it in your MCP config using ${SECRET_NAME} syntax.

json

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/workspace/volumes/my-volume/server.py"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "API_SECRET": "${MY_API_SECRET}"
      }
    }
  }
}

The platform injects the secret values at runtime — they are never exposed in the configuration itself.

Testing

After configuring your MCP server, start a new server session (or restart an existing one) to load the configuration. The Agent will automatically discover the tools provided by your MCP server.

To verify the integration:

Ask the Agent what tools are available — your MCP server's tools should appear in the list.
Ask the Agent to call one of your tools and confirm it returns the expected response.
Check the server terminal for any errors or logs from your MCP server process.

⚠ Warning

MCP configurations are loaded when the server starts. If you add or modify an MCP config, you need to restart the server for changes to take effect.

Best practices

Keep tools focused — Each tool should do one thing well. Prefer many small tools over a few large ones.
Write clear docstrings — The Agent reads these to decide when and how to call your tools. Include parameter descriptions and example usage.
Return actionable responses — Format output as markdown and include clear next steps or suggestions.
Handle failures gracefully — Return error messages the Agent can act on, never let exceptions propagate unhandled.
Validate inputs early — Check that required parameters are present before doing expensive work.
Use secrets for credentials — Never hardcode API keys or passwords in your MCP server configuration.

MCP Servers#

Overview#

Building an MCP server#

Integrating with Agent Studio#

Step 1: Place your server on the server#

Step 2: Configure the MCP server#

Configuration fields#

Step 3: Choose the scope#

Step 4: Use secrets for credentials#

Testing#

Best practices#