Custom MCPs

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.

The Integrations page with the Custom tab selected, showing the Custom MCP card and configured MCP servers like Supabase, Stripe, and Lithic.

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).

Add a Custom MCP dialog with URL type selected, showing fields for Name, Server URL, and optional Headers.

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.).

Add a Custom MCP dialog with Command type selected, showing fields for Name, Command, Arguments, and Environment variables.

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.

Manage Allowed Tools

Control which tools from the MCP server Cyrus is permitted to use. Each tool can be individually toggled on or off.

Configure Allowed Tools dialog showing available tools with individual toggle switches, Select All and Deselect All options.

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

Both methods work together. MCPs configured through the dashboard and through .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

Getting Started

Agent Configuration

Model Providers

Integrations

Security

Advanced

Local Setup

Accessing Custom MCPs