Home / Docs / MCP Servers

MCP Servers

MCP Servers

MCP (Model Context Protocol) servers extend OpenCaddis agents with external tools through a standardized protocol. Agents connect to MCP servers at activation and automatically discover the tools they provide.

Adding an MCP Server

  1. Navigate to Settings > Agent Configuration
  2. Edit an existing agent or create a new one
  3. Scroll to the MCP Servers section
  4. Click Add
  5. Configure the server (see transport types below)
  6. Click Apply, then Save Configuration
  7. Reload agents for changes to take effect

Agents can have multiple MCP servers. All tools from all connected servers are available to the agent alongside its built-in plugins and tools.

Transport Types

Stdio

Launches a local process on the OpenCaddis host. The agent communicates with the process over stdin/stdout.

FieldDescription
NameIdentifier for this server
CommandExecutable to launch (e.g. npx, python, docker run)
ArgumentsCommand-line arguments, one per row
Environment VariablesKey-value pairs passed to the process environment
Runtime Requirements

The host machine must have the required runtime installed (Node.js for npx-based servers, Python for Python-based servers, etc.).

Windows PATH

On Windows, if the command is not on the system PATH for the process running OpenCaddis, use the full path (e.g. C:\Program Files\nodejs\npx.cmd).

Http

Connects to a remote MCP server over HTTP.

FieldDescription
NameIdentifier for this server
URLThe server endpoint
HeadersKey-value pairs sent with each request (e.g. authorization tokens)

Example Configurations

GitHub

FieldValue
Namegithub
TransportStdio
Commandnpx
Arguments-y, @modelcontextprotocol/server-github
EnvGITHUB_PERSONAL_ACCESS_TOKEN = your GitHub PAT

Provides tools for issues, pull requests, repositories, file contents, commits, and more.

Creating a GitHub PAT

GitHub > Settings > Developer Settings > Personal Access Tokens > Fine-grained tokens. Grant permissions for the resources your agent needs (Issues, Pull Requests, Contents, Metadata).

Filesystem

FieldValue
Namefilesystem
TransportStdio
Commandnpx
Arguments-y, @modelcontextprotocol/server-filesystem, /path/to/allowed/directory

Provides tools for reading, writing, and searching files within the specified directory.

Config File Format

MCP servers are stored in opencaddis.json under each agent entry:

opencaddis.json 
{
  "Agents": [
    {
      "Handle": "my-agent",
      "AgentType": "assistant",
      "McpServers": [
        {
          "Name": "github",
          "TransportType": "Stdio",
          "Command": "npx",
          "Arguments": ["-y", "@modelcontextprotocol/server-github"],
          "Env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
          },
          "Url": null,
          "Headers": {}
        },
        {
          "Name": "remote-tools",
          "TransportType": "Http",
          "Command": null,
          "Arguments": [],
          "Env": {},
          "Url": "https://mcp.example.com/sse",
          "Headers": {
            "Authorization": "Bearer token123"
          }
        }
      ]
    }
  ]
}

The TransportType field serializes as a string ("Stdio" or "Http"). Configurations round-trip correctly through export/import.

How FabrCore Handles MCP

OpenCaddis delegates all MCP connectivity to FabrCore. The OpenCaddis config layer stores McpServerConfig objects (a FabrCore type) in the agent configuration DTO and passes them through to AgentConfiguration.McpServers when creating agents via the FabrCore client.

From there, FabrCore's FabrCoreAgentProxy.ResolveConfiguredToolsAsync() connects to each server, discovers tools, and registers them in the agent's tool registry. No agent code (AssistantAgent, DelegateAgent, WorkflowAgent, etc.) needs modification — MCP support is transparent at the framework level.

If a server fails to connect (process not found, network error, timeout), FabrCore logs a warning and the agent continues without that server's tools. Other MCP servers and built-in tools are unaffected.

Troubleshooting

SymptomCauseFix
'npx' is not recognized Node.js not on PATH for the OpenCaddis process Use full path: C:\Program Files\nodejs\npx.cmd
ENOENT ... package.json Trailing whitespace in an argument Re-enter the argument without trailing spaces (the UI trims on save in current builds)
agent will continue without its tools MCP server failed to start or connect Check the server's prerequisites are installed and env vars are correct
Agent initializes but MCP tools missing Server connected but returned no tools Verify the MCP server works standalone (e.g. run the npx command directly in a terminal)
Documentation