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

# MCP Server Configuration

> How MCP servers extend AI agent capabilities with external tools

# MCP Server Configuration

MCP (Model Context Protocol) servers extend the AI agent's capabilities by providing access to external tools and data sources. When you execute tasks via the API, the agent can use tools from your configured MCP servers.

## How MCP Servers Work

MCP servers are configured per-project through the [Console](/console) (not per-request). When you create a task via the API:

1. The system loads your enabled MCP servers from your user configuration
2. The agent connects to these servers and discovers available tools
3. Tools from MCP servers become available alongside built-in tools

<Info>
  MCP server configuration is managed through the [Console](/console) under your project's settings. The Task API automatically uses your project's configured servers.
</Info>

## Supported Transport Types

### HTTP/SSE Transport (Remote Servers)

For remote MCP servers accessible over the network:

```json theme={null}
{
  "url": "https://mcp.example.com",
  "type": "http",
  "enabled": true,
  "headers": {
    "Authorization": "Bearer your-token"
  }
}
```

| Field     | Type                | Description                                                               |
| --------- | ------------------- | ------------------------------------------------------------------------- |
| `url`     | string              | Server URL                                                                |
| `type`    | `'http'` \| `'sse'` | Transport type (`http` for Streamable HTTP, `sse` for Server-Sent Events) |
| `enabled` | boolean             | Whether the server is active                                              |
| `headers` | object              | Custom headers to include in requests                                     |
| `timeout` | number              | Connection timeout in milliseconds                                        |

### Stdio Transport (Local Servers)

For MCP servers that run as local processes:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
  "enabled": true,
  "env": {
    "API_KEY": "your-api-key"
  }
}
```

| Field     | Type      | Description                  |
| --------- | --------- | ---------------------------- |
| `command` | string    | Command to execute           |
| `args`    | string\[] | Command arguments            |
| `enabled` | boolean   | Whether the server is active |
| `env`     | object    | Environment variables        |
| `cwd`     | string    | Working directory            |

## Tool Filtering

Control which tools are available from each MCP server:

```json theme={null}
{
  "url": "https://mcp.example.com",
  "includeTools": ["read_file", "write_file"],
  "excludeTools": ["delete_file"]
}
```

| Field          | Type      | Description                                     |
| -------------- | --------- | ----------------------------------------------- |
| `includeTools` | string\[] | Only allow these tools (allowlist)              |
| `excludeTools` | string\[] | Block these tools (blocklist, takes precedence) |

## Dynamic Token Injection

<Note>
  This feature is for **self-hosted deployments** or applications using the internal Sessions API. The external Tasks API uses server-side user configuration.
</Note>

For advanced deployments, MCP server configuration supports dynamic token injection using the `context` field. This allows passing end-user tokens that get resolved at connection time.

### Template Syntax

Values in `context` can be referenced in `headers` and `env` using `{{mcp.keyName}}`:

```json theme={null}
{
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer {{mcp.token}}",
    "X-Tenant-ID": "{{mcp.tenantId}}"
  },
  "context": {
    "token": "user-specific-jwt-token",
    "tenantId": "tenant-456"
  }
}
```

### Template Resolution Rules

| Rule                 | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| **Syntax**           | Templates use `{{mcp.keyName}}` format                            |
| **Isolation**        | Each server resolves from its own `context` only                  |
| **Missing keys**     | If a key is not found, the original template string is preserved  |
| **Supported fields** | Works with `headers` (all transports) and `env` (stdio transport) |

### Use Case: Per-User Authorization

When building multi-tenant applications where each user has their own credentials for external services:

```json theme={null}
{
  "mcpServers": {
    "inventory-api": {
      "url": "https://inventory.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {{mcp.token}}"
      },
      "context": {
        "token": "eyJ...user-specific-jwt..."
      }
    },
    "billing-api": {
      "url": "https://billing.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {{mcp.token}}"
      },
      "context": {
        "token": "eyJ...different-service-token..."
      }
    }
  }
}
```

Each server's `context` is isolated - one server cannot access another server's tokens.

## Security Considerations

<Warning>
  Never log or expose resolved tokens. The `context` values contain sensitive credentials.
</Warning>

* **Token isolation**: Each server's context is isolated from other servers
* **Secure transmission**: Always use HTTPS for remote MCP servers
* **Token rotation**: Refresh tokens periodically for security
* **Least privilege**: Use `includeTools`/`excludeTools` to limit tool access

## Marketplace-Installed Servers

In addition to manually configuring MCP servers, you can install pre-configured servers from the [MCP Server Marketplace](/console#mcp-server-marketplace) in the Console.

### How It Works

Marketplace servers are installed per-project with a single click:

1. Browse the marketplace catalog and click **Connect**
2. Provide credentials (API key or OAuth) when prompted
3. The server is automatically configured in your project

Marketplace-installed servers appear in your project's MCP server list with a `mkt-` prefix (e.g., `mkt-brave-search`). They work identically to manually configured servers — the agent discovers their tools and can use them in tasks.

### Automatic Credential Injection

When you install a marketplace server with credentials, those credentials are:

* **Encrypted at rest** using AES-256-GCM
* **Automatically injected** into the server config when a session starts
* **Never exposed** in API responses or project configuration

For OAuth-based servers, tokens are automatically refreshed when they expire — no manual re-authentication needed.

<Info>
  You don't need to configure environment variables or headers manually for marketplace servers. The system handles credential injection automatically based on the server template.
</Info>

### Marketplace vs Manual Configuration

| Aspect          | Marketplace                                | Manual                                       |
| --------------- | ------------------------------------------ | -------------------------------------------- |
| **Setup**       | One-click install with credential form     | Configure URL/command, env, headers manually |
| **Credentials** | Encrypted and auto-injected                | Set in `env` or `headers` fields directly    |
| **Updates**     | Version tracking with update notifications | Manual maintenance                           |
| **OAuth**       | Built-in OAuth flow with token refresh     | Must handle tokens yourself                  |

Both approaches can coexist — you can have marketplace servers and manually configured servers in the same project.

***

## Common MCP Servers

Here are some popular MCP servers you can configure:

| Server                                    | Description                |
| ----------------------------------------- | -------------------------- |
| `@modelcontextprotocol/server-filesystem` | File system access         |
| `@modelcontextprotocol/server-github`     | GitHub API integration     |
| `@modelcontextprotocol/server-slack`      | Slack integration          |
| `@modelcontextprotocol/server-postgres`   | PostgreSQL database access |

For more MCP servers, see the [Model Context Protocol](https://modelcontextprotocol.io/) documentation.