Connecting MCP Servers - Craft Agents

Just ask your agent. The easiest way to connect MCP servers is to tell your agent what you need:

“Connect to the Exa search MCP server”
“Add my local filesystem to this workspace”
“Set up the SQLite MCP server for my database”

The agent handles configuration and authentication automatically.

This guide shows you how to connect MCP servers as sources, giving your agents access to external tools and services.

Source Configuration Schema

MCP servers are configured using a standardized source configuration:

{
  "type": "mcp",
  "name": "Server Name",
  "tagline": "Description of the server",
  "icon": "https://example.com/icon.png",
  "mcp": {
    "transport": "http",
    "url": "https://mcp-server.example.com",
    "authType": "oauth"
  }
}

Remote Servers (HTTP/SSE)

For MCP servers accessible over the network, use HTTP transport:

{
  "type": "mcp",
  "name": "Exa Search",
  "tagline": "Neural search and content extraction",
  "icon": "https://exa.ai/favicon.ico",
  "mcp": {
    "transport": "http",
    "url": "https://mcp.exa.ai",
    "authType": "bearer"
  }
}

HTTP transport automatically supports both Streamable HTTP and Server-Sent Events (SSE) protocols based on what the server provides.

Local Servers (Stdio)

For MCP servers that run locally on your machine, use stdio transport:

{
  "type": "mcp",
  "name": "Local MCP",
  "tagline": "MCP Description",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@package/name", "/Users/me/projects"]
  }
}

Common Local Server Patterns

NPX packages:

{
  "type": "mcp",
  "name": "SQLite",
  "tagline": "Query SQLite databases",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
  }
}

Node.js scripts:

{
  "type": "mcp",
  "name": "Custom Server",
  "tagline": "Custom MCP server",
  "mcp": {
    "transport": "stdio",
    "command": "node",
    "args": ["/path/to/my-mcp-server.js"]
  }
}

Python scripts:

{
  "type": "mcp",
  "name": "Python MCP",
  "tagline": "Python-based MCP server",
  "mcp": {
    "transport": "stdio",
    "command": "python",
    "args": ["/path/to/mcp_server.py"]
  }
}

Binary executables:

{
  "type": "mcp",
  "name": "Binary Server",
  "tagline": "Compiled MCP server",
  "mcp": {
    "transport": "stdio",
    "command": "/usr/local/bin/my-mcp-server"
  }
}

Multiple Servers

You can configure multiple MCP sources in your workspace. Each source becomes available with its tools prefixed by the source name:

Using exa_search to find articles...
Using github_list_issues to get open issues...

Server Discovery

When you connect an MCP source, Craft Agents:

Connects to the server using the configured transport
Queries available tools from the server
Makes tools available with prefixed names (e.g., exa_search, github_list_repos)

View connected tools with:

> /tools -v

Refreshing Connections

If a server’s tools change or you need to reconnect:

> /source reload <source-name>

This re-establishes the MCP connection and refreshes available tools.

Troubleshooting

Server not connecting

Verify the URL is correct and accessible (for HTTP transport)
Check if the command exists and is in PATH (for stdio transport)
Check if the server requires authentication
Ensure your network allows the connection
Try accessing the URL directly in a browser (for HTTP)

Tools not appearing

Click the source in the sidebar to view its status
Restart Craft Agents to reload connections
Verify the configuration syntax is correct
Check server logs for errors

Authentication errors

Confirm your API key or token is correct
Check if the key has the required permissions
Some servers need specific scopes - check their documentation
Verify the authType matches what the server expects

Stdio server not starting

Verify the command exists: which npx or which node
Check the arguments are correct
Try running the command manually in terminal to see errors
Ensure required dependencies are installed

Best Practices

Use descriptive names

Choose source names that describe their purpose: web-search, github-repo, company-wiki rather than server1, server2.

Add helpful taglines

Include a tagline that explains what the server does - this helps when browsing available sources.

Include icons when available

Set icon to make sources visually identifiable in the UI. You can use a URL, an emoji, or place an icon.svg or icon.png file in the source folder.

Limit sources per workspace

Connect only the sources your workspace needs. Too many tools can increase response latency and confuse the model about which to use.

Next Steps

Configure authentication

Learn about OAuth, bearer tokens, and public authentication for MCP servers.

​Source Configuration Schema

​Remote Servers (HTTP/SSE)

​Local Servers (Stdio)

​Common Local Server Patterns

​Multiple Servers

​Server Discovery

​Refreshing Connections

​Troubleshooting

​Best Practices

​Next Steps