> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synti.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting MCP Servers

> Step-by-step guide to adding, configuring, and managing MCP servers as sources in Synti.

This page walks through connecting an MCP server to Synti's agent—both by asking the agent and by writing the configuration yourself—plus how to inspect the tools you get and keep servers healthy. For background on what MCP servers are and the two transport types, see the [MCP servers overview](/sources/mcp-servers/overview).

## The fastest path: ask the agent

The simplest way to connect a server is to describe what you want:

> "Connect to the Exa search MCP server."
>
> "Add my local filesystem MCP for the Documents folder."

Synti writes the configuration, prompts you for any credentials, and validates the connection. You rarely need to touch a config file directly—but knowing the schema helps when you want precise control.

## Configuration schema

An MCP source is a folder under your [workspace](/go-further/workspaces) with a `config.json`. The core fields:

| Field     | Purpose                                          |
| --------- | ------------------------------------------------ |
| `type`    | Always `"mcp"`                                   |
| `name`    | Display name for the source                      |
| `slug`    | URL-safe identifier (matches the folder name)    |
| `tagline` | Short description shown in the sources list      |
| `icon`    | Emoji, local path, or URL                        |
| `mcp`     | Transport and authentication details (see below) |

### Remote servers (HTTP / SSE)

For a network-accessible server, use HTTP transport with a URL and an authentication method. Synti supports both Streamable HTTP and Server-Sent Events automatically.

```json config.json theme={null}
{
  "type": "mcp",
  "name": "Exa Search",
  "slug": "exa",
  "tagline": "Web search and content retrieval",
  "enabled": true,
  "mcp": {
    "transport": "http",
    "url": "https://mcp.exa.ai/mcp",
    "authType": "bearer"
  }
}
```

### Local servers (stdio)

For a server that runs on your own machine, use stdio transport and give Synti the command to launch it.

```json config.json theme={null}
{
  "type": "mcp",
  "name": "Filesystem",
  "slug": "filesystem",
  "tagline": "Read and search local files",
  "enabled": true,
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
  }
}
```

`command` is the executable—`npx`, `node`, `python`, or a path to a binary—and `args` are the parameters passed to it. See [Authentication](/sources/mcp-servers/authentication) for setting `authType` and supplying credentials.

## Step by step

<Steps>
  <Step title="Create the source">
    Ask the agent, or add a source folder with a `config.json` using the schema above.
  </Step>

  <Step title="Authenticate">
    Supply an OAuth login or a token if the server needs one. Secrets are encrypted, never stored in config.
  </Step>

  <Step title="Verify the tools">
    Run `/tools -v` to see the tools the server now exposes. Each is prefixed with the source, e.g. `exa_search`.
  </Step>

  <Step title="Use it">
    Ask the agent to do something that needs the server; it selects the right tools on its own.
  </Step>
</Steps>

## Managing connected servers

* **List available tools:** `/tools -v` shows every tool, prefixed by its source so names never collide.
* **Reload a server:** after editing a config or restarting a local server, run `/source reload {slug}` to reconnect and re-read its tools.
* **Enable or disable:** flip `enabled` in `config.json` (or toggle it in the UI) to pause a server without deleting it.
* **Run several at once:** multiple servers can share a workspace. Keep the set focused—each connected server adds startup and tool-selection overhead.

<Tip>
  Give sources descriptive names and helpful taglines, and add an icon. Clear names make the agent's tool choices easier to follow when several servers are connected.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The server won't connect">
    Check the `config.json` for valid JSON, confirm a remote `url` is reachable, and for local servers verify the `command` path resolves and its dependencies are installed.
  </Accordion>

  <Accordion title="Authentication keeps failing">
    Confirm the `authType` matches what the server expects and that your credentials are current. Re-run the OAuth login or re-enter the token, then `/source reload {slug}`.
  </Accordion>

  <Accordion title="Tools don't appear">
    Make sure the source is `enabled`, reload it with `/source reload {slug}`, and re-check `/tools -v`. A local server that failed to start exposes no tools until it launches cleanly.
  </Accordion>
</AccordionGroup>