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

# MCP Servers

> Extend agent capabilities with Model Context Protocol servers

## What is MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that lets AI agents connect to external tools and data sources. MCPs give agents capabilities like browsing the web, querying databases, or interacting with third-party APIs.

## Built-in MCPs

Twill automatically configures these MCP servers for all tasks:

For GitHub access, Twill uses the GitHub CLI (`gh`) inside the sandbox environment (authenticated via `gh auth login`).

| MCP Server   | Capabilities                                   |
| ------------ | ---------------------------------------------- |
| **Context7** | Up-to-date documentation for libraries         |
| **Linear**   | Read and update Linear issues (when connected) |
| **Notion**   | Read and update Notion pages (when connected)  |

<Tip>
  Browser automation and screenshot capture is provided via the{" "}
  <code>agent-browser</code> CLI (not as an MCP server).
</Tip>

## Adding Custom MCPs

You can add custom MCP servers by creating a `.mcp.json` file at the root of any connected repository. Twill detects this file and makes those servers available to the agent when it operates on that repo.

### Configuration Format

Create a `.mcp.json` file with this structure:

```json theme={"theme":"github-dark"}
{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "my-mcp-server@latest"]
    }
  }
}
```

### Server Types

MCP supports two connection types:

| Type      | Description                        | Example                       |
| --------- | ---------------------------------- | ----------------------------- |
| **stdio** | Runs a local command               | `npx`, `uvx`, or any CLI tool |
| **http**  | Connects to a remote HTTP endpoint | `https://mcp.example.com`     |

### Example: Adding a Database MCP

```json theme={"theme":"github-dark"}
{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=readonly"],
      "env": {
        "DATABASE_URI": "${DATABASE_URL}"
      }
    }
  }
}
```

<Tip>
  Use environment variable syntax (`${VAR_NAME}`) to reference secrets.
  Configure these in your workspace environment settings.
</Tip>

### Example: Adding an HTTP MCP

```json theme={"theme":"github-dark"}
{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://mcp.myservice.com",
      "headers": {
        "Authorization": "Bearer ${MY_API_TOKEN}"
      }
    }
  }
}
```