# MCP Integration

MCP (Model Context Protocol) lets you extend LogiCoal with external tools. Connect a GitHub server and the AI can search repos, read issues, and create PRs. Connect a database server and the AI can query your data directly.

MCP tools appear alongside the built-in tools automatically — no special syntax needed.

## Quick Start

Add a server from the curated catalog:

```
/mcp add github
```

The wizard prompts for required environment variables (like API tokens), saves the config, and connects the server. That's it — the AI can now use GitHub tools.

## Curated Catalog

LogiCoal includes a curated catalog of 12 popular MCP servers:

| Name             | Category     | What it provides                     | Required Setup                           |
|------------------|--------------|--------------------------------------|------------------------------------------|
| **github**       | Development  | Repo search, issues, PRs, file access | `GITHUB_PERSONAL_ACCESS_TOKEN`          |
| **filesystem**   | Development  | Extended filesystem operations        | —                                        |
| **sentry**       | Development  | Error tracking and monitoring         | `SENTRY_AUTH_TOKEN`                      |
| **postgres**     | Data         | PostgreSQL query execution           | `POSTGRES_CONNECTION_STRING`              |
| **sqlite**       | Data         | SQLite database access                | `SQLITE_DB_PATH`                         |
| **google-maps**  | Data         | Location, directions, places         | `GOOGLE_MAPS_API_KEY`                   |
| **brave-search** | Search       | Web search via Brave                 | `BRAVE_API_KEY`                         |
| **memory**       | AI           | Persistent knowledge graph            | —                                        |
| **puppeteer**    | Automation    | Browser automation and scraping      | —                                        |
| **slack**        | Communication | Read/send Slack messages             | `SLACK_BOT_TOKEN`, `SLACK_TEAM_ID`       |
| **figma**        | Design       | Access Figma files and components    | `FIGMA_ACCESS_TOKEN`                     |
| **fetch**        | Web          | Advanced URL fetching                 | —                                        |

### Browse the catalog interactively

```
/mcp catalog
```

Use arrow keys to browse by category and select a server to install.

### Add by name

```
/mcp add github
/mcp add postgres
/mcp add puppeteer
```

## Adding Custom Servers

For servers not in the catalog:

```
/mcp add --custom
```

The wizard walks you through:

1. Server name  
2. Transport type (stdio, sse, or streamable-http)  
3. Command and arguments (for stdio) or URL (for sse/streamable-http)  
4. Environment variables  
5. Trust level

### Searching npm

Find MCP servers published on npm:

```
/mcp search database
/mcp search kubernetes
/mcp search aws
```

## Configuration Files

MCP servers are configured in JSON files. You can edit these manually or use the `/mcp add` wizard.

### Global config

`~/.logicoal/mcp.json` — applies to all projects:

```json
{
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      },
      "enabled": true,
      "trustLevel": "supervised",
      "timeout": 30000
    }
  }
}
```

### Project config

`.coals/mcp.json` — applies only to the current project. Servers here override global servers with the same name.

Use project config for servers that are specific to a project (like a local database connection).

### Config fields

| Field         | Required | Description                                                                         |
|---------------|----------|-------------------------------------------------------------------------------------|
| `transport`   | Yes      | `stdio`, `sse`, or `streamable-http`                                                |
| `command`     | stdio only| The command to run (e.g., `npx`)                                                  |
| `args`        | stdio only| Command arguments as an array                                                       |
| `url`         | sse/http only| The server URL                                                                     |
| `env`         | No       | Environment variables passed to the server process                                   |
| `enabled`     | No       | `true` or `false` (default: `true`)                                                 |
| `trustLevel`  | No       | `supervised`, `autonomous`, or `readonly` (default: `supervised`)                  |
| `timeout`     | No       | Connection timeout in milliseconds (default: `30000`)                               |

### Transport types

- **stdio** — Most common. Runs a local process that communicates via stdin/stdout. Used by most npm MCP packages.
- **sse** — Connects to an HTTP server using Server-Sent Events.
- **streamable-http** — Connects to an HTTP server using streaming HTTP.

## Managing Servers

| Command                            | Description                                     |
|------------------------------------|-------------------------------------------------|
| `/mcp` or `/mcp servers`          | Show all servers and their connection status    |
| `/mcp tools`                      | List all tools from all connected servers       |
| `/mcp tools github`               | List tools from a specific server               |
| `/mcp connect github`              | Connect to a configured server                  |
| `/mcp disconnect github`           | Disconnect a running server                      |
| `/mcp remove github`               | Remove a server from config and disconnect it   |
| `/mcp reload`                      | Reload config files and reconnect all servers   |

## Trust Levels

Each MCP server has a trust level that controls tool approval:

- **supervised** — Tool calls require approval in Normal mode
- **autonomous** — Tool calls run without approval
- **readonly** — Server tools can only read, not write

## How MCP Tools Appear

MCP tools are named `mcp__<server>__<tool>`. For example, GitHub tools might appear as:

```
mcp__github__search_repositories
mcp__github__create_issue
mcp__github__get_file_contents
```

You don't need to remember these names — just describe what you want and the AI will use the appropriate tool.

## Agents and MCP

All agent roles have access to MCP tools by default (via `mcp__*` in their allowed tools). This means your agents can use GitHub, databases, or any other connected MCP server without additional configuration.