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.
Takes you to Allowed Tools per Platform (/settings/tools), where the chosen MCP’s tools live as mcp__<slug>__<tool> entries on the Slack / Linear / GitHub tabs. Toggling them on or off there is what enables or disables them for each surface — it is the single source of truth.
The initial tool selection happens inline when you first connect the MCP (under Add Custom MCP). After that, the dropdown link is just a shortcut to the page where you can adjust the gating per platform.
If no tools are allowed on any platform, 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 on the platforms you care about.
Remove
Permanently removes the MCP server from your workspace. This does not affect any .mcp.json files in your repositories.
Enabling and disabling MCPs
Enable/disable happens on Allowed Tools per Platform (/settings/tools), not on this page. Toggle individual tools — or the whole MCP server — on or off per surface (Slack, Linear, GitHub) and per repository override. A custom MCP server appearing in the MCP Servers section of every tab is the normal state; whether it’s actually used in a given session is determined by which of its tools are enabled on that surface.
To remove an MCP server entirely, use Manage > Remove here on /integrations.
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 on the platform you’re using under Allowed Tools per Platform (
/settings/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
