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 (not per-request). When you create a task via the API:

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

MCP server configuration is managed through the Console under your project’s settings. The Task API automatically uses your project’s configured servers.

Supported Transport Types

HTTP/SSE Transport (Remote Servers)

For remote MCP servers accessible over the network:

{
  "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:

{
  "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:

{
  "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

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

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}}:

{
  "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	The server fails to connect with an error naming the placeholder and the keys that were available; the literal placeholder is never sent upstream. Names are case-sensitive, and an empty value counts as missing
Supported fields	Works with `headers` (all transports), `env` (stdio transport) and `url`

Use Case: Per-User Authorization

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

{
  "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

Never log or expose resolved tokens. The context values contain sensitive credentials.

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 in the Console.

How It Works

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

Browse the marketplace catalog and click Connect
Provide credentials (API key or OAuth) when prompted
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.

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.

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 documentation.

Getting Started

Chat UI

Embeddable Widget

Task API

Concepts

Examples

MCP Server Configuration

MCP Server Configuration

How MCP Servers Work

Supported Transport Types

HTTP/SSE Transport (Remote Servers)

Stdio Transport (Local Servers)

Tool Filtering

Dynamic Token Injection

Template Syntax

Template Resolution Rules

Use Case: Per-User Authorization

Security Considerations

Marketplace-Installed Servers

How It Works

Automatic Credential Injection

Marketplace vs Manual Configuration

Common MCP Servers

​MCP Server Configuration

​How MCP Servers Work

​Supported Transport Types

​HTTP/SSE Transport (Remote Servers)

​Stdio Transport (Local Servers)

​Tool Filtering

​Dynamic Token Injection

​Template Syntax

​Template Resolution Rules

​Use Case: Per-User Authorization

​Security Considerations

​Marketplace-Installed Servers

​How It Works

​Automatic Credential Injection

​Marketplace vs Manual Configuration

​Common MCP Servers

MCP Server Configuration

How MCP Servers Work

Supported Transport Types

HTTP/SSE Transport (Remote Servers)

Stdio Transport (Local Servers)

Tool Filtering

Dynamic Token Injection

Template Syntax

Template Resolution Rules

Use Case: Per-User Authorization

Security Considerations

Marketplace-Installed Servers

How It Works

Automatic Credential Injection

Marketplace vs Manual Configuration

Common MCP Servers