Cyrus supports custom MCP (Model Context Protocol) servers, allowing your agent to interact with external APIs, databases, and services during sessions. You can add, configure, and manage MCP servers directly from the Cyrus dashboard — no code changes required.
OAuth-based MCP authentication is not supported. Custom MCPs must use API key or token-based authentication. When choosing an MCP server, look for configurations that authenticate via API keys, bearer tokens, or headers rather than OAuth flows. Most MCP server providers offer a key-based authentication option alongside OAuth.
For file-based MCP configuration using .mcp.json in your repository, see the MCP Servers guide. The dashboard approach described here and the file-based approach work together — MCPs added through either method are available to Cyrus during sessions.
Accessing Custom MCPs
Navigate to the Integrations page and select the Custom tab to view and manage your MCP servers.
From here you can:
- Add new custom MCP servers
- Enable or disable existing MCPs using the toggle switch
- Manage MCP settings, allowed tools, or remove MCPs
Adding a Custom MCP
Click the + Add custom MCP button on the Custom MCP card. You’ll see a dialog with two configuration modes: URL and Command.
URL-Based MCP
Use this for MCP servers accessible over HTTP/HTTPS (remote servers, hosted services).
| Field | Description |
|---|
| Name | A unique identifier for the MCP server (e.g., supabase, lithic) |
| Server URL | The full URL of the MCP server endpoint (e.g., https://mcp.supabase.com/mcp?project_ref=...) |
| Headers | Optional key-value pairs for authentication or custom headers |
Command-Based MCP
Use this for MCP servers that run as local processes (stdio-based servers started via npx, node, etc.).
| Field | Description |
|---|
| Name | A unique identifier for the MCP server (e.g., stripe) |
| Command | The executable to run (e.g., npx) |
| Arguments | Command arguments, added one per row (e.g., @stripe/mcp-server) |
| Environment | Key-value pairs for environment variables the server needs (e.g., API keys) |
JSON Editor
For advanced configurations, click Edit JSON at the bottom of the dialog to switch to a raw JSON editor. This uses the same mcpServers format as .mcp.json files.
You can switch back to the form view by clicking Edit Form.
The JSON editor is useful when you already have an MCP configuration from a .mcp.json file and want to paste it directly.
Managing MCPs
Each configured MCP server has a Manage button with three options:
Manage Settings
Edit the MCP server’s configuration — update the URL, command, arguments, environment variables, or headers.
Control which tools from the MCP server Cyrus is permitted to use. Each tool can be individually toggled on or off.
The dialog shows all available tools discovered from the MCP server, with descriptions for each. Use Select All or Deselect All for bulk changes, or toggle individual tools as needed. Click Confirm allowed tools to save, or Skip to keep the current configuration.
If no tools are allowed, Cyrus will connect to the MCP server but won’t be able to use any of its capabilities. Make sure to allow at least the tools you want Cyrus to use.
Remove
Permanently removes the MCP server from your workspace. This does not affect any .mcp.json files in your repositories.
Enabling and Disabling MCPs
Each MCP server card has a toggle switch in the top-right corner. Use it to temporarily disable an MCP server without removing its configuration. Disabled MCPs won’t be loaded during agent sessions.
Examples
Here are some common MCP servers you might add:
| MCP Server | Type | Description |
|---|
| Stripe | Command | Query payments, refunds, and customers using the Stripe MCP server (npx @stripe/mcp-server) |
| Supabase | URL | Access your Supabase project’s database and APIs via the hosted MCP endpoint |
| Sentry | Command | Query error reports and performance data from your Sentry projects |
Many services now offer official MCP servers. Check your service provider’s documentation to see if they support MCP.
Dashboard vs File-Based Configuration
Cyrus supports two ways to configure MCP servers:
| Dashboard (this page) | File-based (.mcp.json) |
|---|
| Where | Integrations > Custom tab | .mcp.json at repository root |
| Scope | Workspace-wide — applies to all repositories | Per-repository |
| Best for | Shared services (Stripe, Supabase), quick setup | Repo-specific tools, version-controlled configs |
| Secrets | Entered directly in the dashboard | Referenced via ${ENV_VAR} placeholders |
.mcp.json files are merged and available during agent sessions.
For detailed guidance on file-based MCP configuration, see the MCP Servers guide.
Troubleshooting
MCP server tools aren’t being called
- Verify the MCP is enabled (toggle is on)
- Check that the tools you need are allowed via Manage > Manage allowed tools
- For command-based MCPs, ensure the command and arguments are correct
- For URL-based MCPs, verify the server URL is accessible
MCP server fails to connect
- For URL-based servers, confirm the URL is correct and the server is running
- For command-based servers, ensure the command is available in the runtime environment
- Check that any required environment variables or headers are configured
Tools appear but Cyrus doesn’t use them
- Cyrus only calls MCP tools when relevant to the task. Include guidance in your Linear issue description (e.g., “Use Stripe to check recent charges”)
- Verify the tools are allowed — disabled tools won’t appear in Cyrus’s available tool list
Cyrus Community
Get support and ask questions on Discord
