> ## Documentation Index > Fetch the complete documentation index at: https://atcyrus.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP Servers > Connect custom MCP servers (like Stripe) so Cyrus can safely interact with external systems. Cyrus supports **custom MCP (Model Context Protocol) servers**, which allow it to interact with external systems during tasks like debugging, validation, and analysis. You can add **any MCP server** (external providers, internal services, third-party APIs) as long as: * It’s defined in your repository * Secrets are provided via environment variables * The tools are explicitly allowed This guide walks through setup using **Stripe** as a concrete example. Support for OAUTH driven authentication for 'remote' MCP servers is not yet supported for Cloud-hosted runtimes ## What you’re setting up (mental model) 1. `.mcp.json` defines **which MCP servers exist** and **what they need** 2. Environment variables provide **secrets (API keys, tokens)** 3. Allowed Tools define **what Cyrus is permitted to call** — configured per platform (Slack / Linear / GitHub) on **[Allowed Tools per Platform](/allowed-tools)** (`/settings/tools`) Environment variables for MCP servers depend on how you run Cyrus: * **Hosted / Team plans**:\ Environment variables are configured in the Cyrus web app and injected automatically. * **Self-hosted or Semi-hosted**:\ Environment variables must be set on **your own machines or infrastructure** where Cyrus runs. If Cyrus cannot access the environment variables at runtime, MCP servers will not start. ## Step 1 — Define the Stripe MCP server (`.mcp.json`) Start by adding a `.mcp.json` file to the **root of your repository** and ensure it gets merged to the branch considered by Cyrus to be the default branch. This file declares: * The MCP server name * How to start it * Which environment variables it expects ### Example: Stripe MCP server ```json theme={null} { "mcpServers": { "stripe": { "command": "npx", "args": ["@stripe/mcp-server"], "env": { "STRIPE_API_KEY": "${STRIPE_API_KEY}" } } } } ``` ### What’s happening here * `stripe` is the **server name** * No secrets are committed * `${STRIPE_API_KEY}` is a placeholder, which will be automatically replaced with the value associated with the `STRIPE_API_KEY` environment variable in your shell Reference: [https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json) *** ## Step 2 — Provide environment variables How you provide variables depends on your deployment mode. ### Cloud-hosted runtime In the Cyrus web app: 1. Go to [Repos](https://app.atcyrus.com/repos) 2. Click the vertical **ellipsis menu (⋯)** 3. Select 'Environment variables' 4. Add the following environment variable to a '.env' file at the repository root: ``` STRIPE_API_KEY = sk_live_... ``` ### Self-hosted runtime Set the variable on the machine where `cyrus` is running: ```bash theme={null} export STRIPE_API_KEY=sk_live_... ``` *** ## Step 3 — Allow Stripe MCP tools Even with the server defined and secrets configured, Cyrus will **not** call MCP tools unless they’re explicitly allowed. This is a safety boundary. *** ### How MCP tool names work Cyrus namespaces MCP tools using this format: ``` mcp__ mcp____ ``` For the Stripe server: * Allow **all Stripe tools** ``` mcp__stripe ``` * Allow a **single tool only** ``` mcp__stripe__retrieve_charge ``` If you’re unsure which tools you’ll need, start by allowing the server. ### Where to configure allowed tools Tool gating lives on **[Allowed Tools per Platform](/allowed-tools)** (`/settings/tools` in the Cyrus webapp). It is configured **per platform** (Slack / Linear / GitHub) — Cyrus is reachable from each of those surfaces independently, and each has its own allow-list: * **Slack** — Cyrus replying to `@mentions` * **Linear** — Cyrus working a Linear issue * **GitHub** — Cyrus reacting to a PR comment or webhook Open the tab for the surface you care about, find the **MCP Servers** section, and toggle the server's tools on. You can: * Toggle the whole server on (`mcp__stripe`) to allow every tool it exposes * Toggle individual tools on (`mcp__stripe__retrieve_charge`) for narrower access #### Per-repository overrides If you want a specific repository to deviate from the team-level platform list, open that repo's row on `/settings/tools` and use **Allowed Tools** to set a custom list. The override applies to both Linear and GitHub sessions on that repo (Slack is repo-agnostic and has no per-repo override). The MCP Servers section is available inside the dialog too, so per-repo MCP gating works the same way. If a tool is not enabled on the relevant tab (or, when a repo override is active, in that override), Cyrus will refuse to call it even if instructed. ## Setup complete At this point: * Stripe MCP server is defined * Stripe API key is configured * Tool permissions are granted Cyrus is now capable of interacting with Stripe. *** ## Using MCP from a Linear issue Create a Linear issue and include guidance in the **title or description**. ### Example instructions * “Use Stripe to check whether this customer was charged twice” * “Query recent Stripe payment failures and summarize the issue” * “Validate whether the refund was successfully processed in Stripe” Cyrus will: * Detect the instruction * Call the Stripe MCP tools (if allowed) * Use the results during reasoning or debugging *** ## Common pitfalls ### MCP tools aren’t being called Check: * `.mcp.json` exists at the repo root * Any environment variable the MCP server needs (server specific) is available at runtime * `mcp__` (allow all) or `mcp____` is listed in [Allowed Tools](https://app.atcyrus.com/settings/tools) ### Secrets were committed **Rotate the key immediately,** then: * Remove it from git * Move it into environment variables * Reference it using `${YOUR_ENV_VAR}` *** *** Get support and ask questions on Discord