Skip to main content
The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external data sources and tools.

​
What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how AI applications communicate with external data sources. Instead of building custom integrations for every service, MCP provides a universal interface that works across all compatible servers.

​
Key Benefits

Universal Protocol

One standard interface works with hundreds of MCP servers

Real-time Data

Access live data from external services during agent sessions

Extend Capabilities

Add new tools and functionality without modifying core code

Community Ecosystem

Growing library of pre-built servers for popular services

​
MCP Architecture

Craft Agents implements MCP through a centralized client pool that manages all source connections:

​
How It Works

1

Configure Source

Create a source configuration with connection details (URL or command)
2

Connect to Server

The MCP client pool establishes connection using the specified transport
3

List Tools

Server exposes available tools through the MCP protocol
4

Execute Tools

Agent can call tools during sessions with automatic auth and result handling

​
MCP Transports

Craft Agents supports two transport mechanisms for connecting to MCP servers:

​
HTTP/SSE Transport

For remote MCP servers accessible via HTTP or Server-Sent Events: 
{
  "type": "mcp",
  "mcp": {
    "transport": "http",
    "url": "https://api.example.com/mcp"
  }
}
HTTP transport automatically appends /mcp to URLs if not present. The Craft MCP server uses this transport.

​
Stdio Transport

For local MCP servers that run as subprocesses: 
{
  "type": "mcp",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"]
  }
}
Local MCP servers run as subprocesses. Sensitive environment variables (API keys, tokens) are automatically filtered to prevent credential leakage.

​
MCP Authentication

MCP servers support multiple authentication methods:

​
No Authentication

For public or local servers that don’t require credentials: 
{
  "authType": "none"
}

​
Bearer Token

For servers that use bearer token authentication: 
{
  "authType": "bearer"
}
The app will prompt you to enter the bearer token during source setup. Credentials are encrypted with AES-256-GCM and stored in ~/.craft-agent/credentials.enc.

​
OAuth 2.0

For services that use OAuth 2.0 (like Craft, Slack): 
{
  "authType": "oauth",
  "oauth": {
    "authorizationUrl": "https://api.example.com/oauth/authorize",
    "tokenUrl": "https://api.example.com/oauth/token",
    "clientId": "your-client-id",
    "scope": "read write"
  }
}

​
Custom Headers

For HTTP/SSE transport with custom authentication: 
{
  "mcp": {
    "transport": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "X-API-Key": "your-api-key",
      "X-Custom-Header": "value"
    }
  }
}

​
Security

​
Credential Storage

All credentials are encrypted with AES-256-GCM before being stored on disk:
  • Storage location: ~/.craft-agent/credentials.enc
  • Encryption: Industry-standard AES-256-GCM
  • Access: Only the Craft Agents app can decrypt credentials

​
Local MCP Isolation

When spawning local MCP servers (stdio transport), sensitive environment variables are filtered: Blocked variables:
  • ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN (app auth)
  • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
  • GITHUB_TOKEN, GH_TOKEN, OPENAI_API_KEY, GOOGLE_API_KEY
  • STRIPE_SECRET_KEY, NPM_TOKEN
To explicitly pass environment variables to a specific MCP server, use the env field in the source config.

​
Tool Naming Convention

When MCP servers are connected, their tools are exposed with a namespaced prefix: 
mcp__{sourceSlug}__{toolName}
Example:
  • Source slug: linear
  • Tool name: createIssue
  • Full tool name: mcp__linear__createIssue
This prevents naming conflicts when multiple sources provide similar tools.

​
Connection Management

The MCP client pool manages all source connections:
  • Persistent connections: Sources remain connected for the session lifetime
  • Automatic reconnection: Failed connections are retried automatically
  • Tool caching: Tool definitions are cached after first connection
  • Graceful shutdown: All connections are closed when the app exits

​
Next Steps

Craft MCP Server

Connect to your Craft workspace with 32+ document tools

Custom MCP Servers

Add your own MCP servers via HTTP/SSE or local commands

Build docs developers (and LLMs) love

Get started for freeTalk to us