MCP

The Model Context Protocol (MCP) is an open standard for connecting LLMs to external tools and data sources. ScalyClaw supports MCP natively — register a server, and its tools are auto-discovered and made available to the LLM alongside all built-in tools, with no additional prompt engineering required.

Integration

MCP defines a structured, transport-agnostic protocol between a host (ScalyClaw) and one or more servers (external processes that expose tools). The host connects to a server, calls tools/list to discover what tools are available, and then forwards tools/call requests as the LLM uses those tools during conversation. The LLM sees MCP tools exactly the same way it sees built-in tools — as named functions with a JSON Schema input definition.

ScalyClaw supports three MCP transports:

Transport	Description	Best for	Considerations
`stdio`	ScalyClaw spawns the MCP server as a child process and communicates over stdin/stdout using newline-delimited JSON.	Local tools — filesystem access, shell commands, local databases. Zero network overhead, tight lifecycle coupling.	Server process runs on the same machine. If ScalyClaw restarts, the server process is also restarted.
`http`	ScalyClaw connects to an MCP server exposed over HTTP. Requests and responses are JSON over standard HTTP POST.	Remote tools, shared infrastructure, servers that need to run independently and serve multiple clients.	Requires network access. Server lifecycle is independent — it can be deployed anywhere and upgraded without restarting ScalyClaw.
`sse`	Server-Sent Events variant of HTTP transport. The server pushes streaming responses over a persistent connection.	Tools that produce long-running or incremental results — web scraping, large file processing, streaming search.	Requires an SSE-compatible server. Adds connection-management overhead compared to plain HTTP.

Auto-Discovery

When a connection to an MCP server is established, ScalyClaw immediately calls tools/list to retrieve the server's full tool manifest. Each tool in the manifest — its name, description, and JSON Schema input definition — is merged into the active tool set and injected into the system prompt. The LLM sees them as first-class tools with no distinction from built-in ones.

Discovery also runs on hot-reload. When a scalyclaw:skills:reload pub/sub signal is published to Redis, ScalyClaw re-queries all connected MCP servers and refreshes the tool list without a restart. This means you can update an MCP server's tool manifest and have the change picked up within seconds.

Execution stays in the worker

MCP tool calls are routed through the tools BullMQ queue, not executed inline in the Node process. The worker holds the MCP client connections and handles all tools/call requests on behalf of the orchestrator. This means MCP tools benefit from the same isolation and back-pressure handling as execute_code and execute_skill.

Connecting Servers

MCP servers are managed from the Settings → MCP Servers page in the ScalyClaw dashboard. The workflow is:

Add a server. Click Add MCP Server and fill in the name, transport type, and either the command (for stdio) or URL (for http / sse). For stdio servers you can also specify environment variables — these are resolved from the secret vault at connection time, so you can reference secrets by name rather than embedding values directly.
Test the connection. The dashboard sends a tools/list request and displays the discovered tools. If the connection fails, a structured error is shown — see the troubleshooting notes below.
Save. The server configuration is persisted to Redis. ScalyClaw connects to it immediately and the discovered tools become available to the LLM in the next conversation turn.

Configuration JSON

You can bulk-import server configurations by pasting or uploading a JSON object. This is useful when migrating an existing MCP setup or when you want to version-control your server list. The format follows the MCP client configuration convention:

json

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"],
      "env": {}
    },
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "secret:github_token"
      }
    },
    "web-search": {
      "transport": "http",
      "url": "https://mcp.example.com/search",
      "headers": {
        "Authorization": "secret:search_api_key"
      }
    }
  }
}

Values prefixed with secret: are resolved from the ScalyClaw secret vault at connection time. The raw secret value is never stored in the server configuration — only the reference name is persisted to Redis.

Popular MCP servers to try

The MCP ecosystem has a growing library of ready-to-use servers. A few well-maintained options: @modelcontextprotocol/server-filesystem for reading and writing local files, @modelcontextprotocol/server-github for interacting with GitHub repositories and issues, @modelcontextprotocol/server-postgres for querying a PostgreSQL database, and @modelcontextprotocol/server-brave-search for live web search via the Brave Search API. All are available on npm and work with the stdio transport.

Troubleshooting

Error	Likely cause	Fix
Command not found	The executable specified in `command` is not on the PATH of the process running the ScalyClaw worker.	Use an absolute path to the binary, or ensure the relevant package is installed globally. For `npx`-based servers, verify Node and npm are installed in the worker's environment.
Connection refused	For `http` or `sse` transports: the server is not running at the specified URL, or a firewall is blocking the connection.	Confirm the server is running and reachable from the machine hosting the ScalyClaw worker. Check port bindings and firewall rules.
Timeout on `tools/list`	The server process started but is not responding to the initial handshake. Common with `stdio` servers that have slow startup (e.g. JVM or Python startup overhead).	Increase the connection timeout in the server settings. If the server is consistently slow to start, consider switching to `http` transport and running it as a persistent service.
Secret not resolved	An environment variable or header value references a secret name that does not exist in the vault.	Go to Settings → Secrets and add the missing secret. The key must match the name used after the `secret:` prefix exactly.