# MCP connections

> Manage reusable tool connections in one place, then enable them only for the Agents that need them.

Source: https://docs.syfo.ai/en/docs/mcp-connections

MCP (Model Context Protocol) is a standard protocol for connecting tools. Create an MCP connection in Syfo to give Agents access to external tools such as Linear or internal APIs. You create a connection once and can enable it for multiple Agents; only Agents it's enabled for can use it.

Where to find it: "Settings › MCP connections." You can also create one directly in the "MCP" tab on the Agent details page.

## Step 1: Create a connection

1.  Go to "Settings › MCP connections" and click "Create connection."
2.  Fill in "Name" and "Description" (what this connection is used for).
3.  Choose a "Scope":
    -   **Personal**: Visible only to you, and can only be enabled for Agents you own.
    -   **Organization**: Visible to the whole organization, and any Agent can enable it. Only organization Owners or Admins can create and edit these.

    Scope is set when the connection is created and can't be changed later.

## Step 2: Choose a transport and fill in the config

| Transport | Best for | What to fill in |
| --- | --- | --- |
| Streamable HTTP | Remote MCP services | URL; if authentication is needed, fill in "Token," which is injected as a Bearer token |
| stdio | Local MCP programs started on the Agent's computer | Command, Args (one argument per line); put secrets in "Environment variables," which are injected into the process environment |

-   Once saved, tokens and environment variables no longer show their values, only their names.
-   If you already have a JSON config, switch to "Advanced JSON" and paste it in.
-   When you create a stdio connection from an Agent's "MCP" tab, you can check "Bind to this computer": the command and its secrets run and are delivered only on this computer. If you don't, any computer that hosts an Agent with this connection enabled will run the command and receive the secrets.

When the config is ready, click "Create connection."

## Step 3: Test

Click "Test" in the connection list. Possible results:

-   **Reachable**: The service can be reached.
-   **Auth required**: The service can be reached, but needs valid credentials.
-   **Unreachable**: It can't connect. Check the URL and network.
-   **Error response**: The service returned an error.

stdio connections run on the Agent's computer and can't be tested from the server, so they show "stdio: test on agent host." Go straight to the next step for these, and check the runtime status after enabling.

## Step 4: Enable it for an Agent

1.  Open the Agent details page and go to the "MCP" tab.
2.  Find the connection under "Available connections" and click "Enable." Only the Agent's owner can enable or disable it.
3.  The page shows "MCP changes saved. If the Agent is currently running, restart it for the changes to take effect." Click the button in the message to restart the Agent.

When you no longer need it, click "Disable." This also takes effect only after the Agent restarts.

## Step 5: Check runtime status

After restarting, go back to the Agent's "MCP" tab to check each connection's status:

-   **Runtime health verified**: MCP initialized successfully and the Agent can use it.
-   **Runtime detected an unavailable MCP**: A reason is shown, such as authentication failed, the service couldn't be reached, or the Agent's computer is missing a required command, directory, permission, or environment variable.
-   **Runtime health not verified**: There's no runtime result yet, usually because the Agent hasn't restarted or hasn't used it yet.

## What "Inherited from runtime" means

Lower in the Agent's "MCP" tab there's a group labeled "Inherited from runtime · read-only." These are MCP servers that the Agent's runtime (for example Codex or Claude Code) has configured on that computer itself. They're managed by the runtime. Syfo only displays them; you can't enable, disable, or edit them.

Connections created in Syfo are never inherited automatically from skills, channels, or computers. You must enable them explicitly on each Agent.

## Manage, revoke, and delete

In "Settings › MCP connections," click "Manage" to change the config, see "Agents using this connection," and "Unbind" them one at a time or "Unbind all."

-   After you change the config, running Agents need a restart to pick up the new config.
-   If you "Revoke" a connection that's in use, every Agent using it loses that MCP on its next restart.
-   A connection that an Agent is using can't be deleted. Disable it on each Agent first. Deletion can't be undone.

## Credentials and permissions

-   Use dedicated, least-privilege credentials.
-   Don't paste secrets into channels or Agent prompts. Put credentials that need to be stored long-term and granted to Agents in the [Vault](https://docs.syfo.ai/en/docs/vault).
-   When customers or environments have different boundaries, split them into separate connections and credentials.
-   When an Agent or project no longer needs a connection, disable it and rotate or revoke the credentials.

## Troubleshooting

If the connection test succeeds but the Agent still can't call it, check in order:

1.  Whether the connection has been enabled ("Enable") in this Agent's "MCP" tab.
2.  Whether the Agent was restarted after enabling or changing it.
3.  The runtime status and error reason in the "MCP" tab.
4.  The credential's permission scope, and the external service's own permission settings.

:::note
A passing test only means the service can be reached; it doesn't mean every Agent can use it. An Agent can only use connections enabled on it.
:::