RoboSystems MCP Client

Official MCP (Model Context Protocol) stdio bridge for connecting stdio-only AI clients to the RoboSystems financial intelligence platform. Query financial statements, explore graph structures, resolve XBRL elements, and build fact grids.

The preferred way to connect is the hosted remote MCP endpoint — no install required. Every RoboSystems graph serves the MCP Streamable HTTP transport directly. OAuth-capable clients (claude.ai, Claude Code, ChatGPT, VS Code, Cursor) add https://api.robosystems.ai/v1/mcp, sign in, and pick the graph on the consent screen; any HTTP-capable client can instead add a per-graph URL https://api.robosystems.ai/v1/graphs/{graph_id}/mcp with an API key in the X-API-Key header. This npx package is in maintenance mode and exists only for clients that speak nothing but the stdio transport: it is a transparent proxy that forwards that same transport over stdio. See Migrating to the remote endpoint.

Features

• Native MCP transport over stdio — a transparent proxy that forwards the graph's Streamable HTTP endpoint verbatim: per-session instructions, live tool lists, and streamed progress notifications, identical to connecting the URL directly
• Every server tool, as the server advertises it — financial statements, disclosures and fact grids; Cypher, schema introspection and element resolution; subgraphs and agent memory on graphs that have them

Installation

Add to your MCP servers configuration:

{
  "mcpServers": {
    "robosystems": {
      "command": "npx",
      "args": ["-y", "@robosystems/mcp@latest"],
      "env": {
        "ROBOSYSTEMS_API_URL": "https://api.robosystems.ai",
        "ROBOSYSTEMS_API_KEY": "rfs...",
        "ROBOSYSTEMS_GRAPH_ID": "kg..."
      }
    }
  }
}

Environment Variables

Variable	Description	Default
ROBOSYSTEMS_API_KEY	Your API key, sent as X-API-Key	(required)
ROBOSYSTEMS_GRAPH_ID	The graph to connect (derives the per-graph endpoint URL)	(required unless ROBOSYSTEMS_MCP_URL is set)
ROBOSYSTEMS_API_URL	API endpoint	https://api.robosystems.ai
ROBOSYSTEMS_MCP_URL	Full MCP endpoint URL — overrides the URL derived from graph ID	(derived from graph ID)

How it works

By default this package is a transparent pipe between your stdio client and the graph's native MCP endpoint (POST /v1/graphs/{graph_id}/mcp, Streamable HTTP). Every JSON-RPC message is forwarded verbatim, so per-session instructions, the live server tool list, and streamed progress notifications behave exactly as they do when connecting the URL directly — the only thing the proxy adds is the API-key header the stdio client can't send itself. The standard configuration above is all it needs.

To target a specific endpoint (for example a local stack), point ROBOSYSTEMS_MCP_URL at the full URL, e.g. http://localhost:8000/v1/graphs/kg.../mcp — no graph ID needed.

Migrating to the Remote Endpoint

If your client supports HTTP transports, replace the npx entry with a direct connection — the URL picks the graph (sec for the public SEC repository, your kg… graph id for your own; a subgraph id like kg…_dev is just another URL), and your account-wide API key goes in the X-API-Key header, one connector per graph.

OAuth — sign in and pick a graph (claude.ai, Claude Code, ChatGPT, VS Code, Cursor): add the graph-agnostic endpoint and no key at all; the consent screen is where you choose the graph.

claude mcp add --transport http robosystems https://api.robosystems.ai/v1/mcp

Claude Code with an API key — one command:

claude mcp add --transport http robosystems-sec \
  https://api.robosystems.ai/v1/graphs/sec/mcp \
  --header "X-API-Key: <your key>"

Cursor / VS Code — replace the command/args/env entry in mcp.json with:

"robosystems-sec": {
  "url": "https://api.robosystems.ai/v1/graphs/sec/mcp",
  "headers": { "X-API-Key": "<your key>" }
}

Local development uses the same shape against a local stack: http://localhost:8000/v1/graphs/{graph_id}/mcp.

Claude (claude.ai / Desktop) — Settings → Connectors → Add custom connector with https://api.robosystems.ai/v1/mcp (or a per-graph URL): Claude detects OAuth and you pick the graph at sign-in; no key involved. Credentials never travel in the URL — the older ?token= connector URL was the bridge to OAuth and has been retired. Claude Desktop can alternatively run this package via claude_desktop_config.json (the config file accepts only stdio-shaped command entries); in its default proxy mode it delivers the same remote-endpoint behavior over stdio with the key in a header.

Tools

Tools are loaded dynamically from the RoboSystems API based on your graph, so the authoritative list is whatever your server advertises — the proxy adds nothing of its own. The tables below are representative.

Financial Data

Tool	Description
get-financial-statement	Retrieve structured financial statements (income, balance sheet, cash flow) by ticker and period
list-disclosures	List available disclosure types with counts, optionally filtered by ticker
get-disclosure-detail	Get facts for a specific disclosure type
build-fact-grid	Construct multidimensional fact grids from graph data for analysis

Graph Exploration

Tool	Description
execute-cypher	Run Cypher queries against the knowledge graph with validation and streaming
get-graph-schema	Introspect node types, relationships, and properties
describe-graph-structure	Explore graph structure and relationship patterns
get-graph-info	Graph metadata and statistics
resolve-element	Map financial concepts (e.g. "revenue") to XBRL element qnames
resolve-structure	Find financial statement structures by type
get-properties	Discover available properties on node types
get-example-queries	Query templates and examples for common patterns

Resources

• RoboSystems Platform
• GitHub Repository
• API Documentation
• OpenAPI Specification

Support

• Issues
• Wiki
• Projects
• Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT © 2026 RFS LLC