Using SolidX MCP Server
Expose SolidX tools to external AI clients over HTTP with the SolidX MCP server.
The MCP server exposes SolidX tools to external AI clients (Claude Code, Claude Desktop, Cursor, Codex CLI, etc.) over HTTP with API-key authentication.
Prerequisite: bootstrap a project first
This guide assumes you have already scaffolded and started a SolidX project using solidctl create-app and solidctl start:dev, as described in the main Getting Started guide. The MCP server runs against an existing project's backend - it does not create one.
Connect your AI agent
solidctl mcp install detects which supported AI agents are installed on your machine and writes the SolidX MCP server entry into each agent's config automatically. This is a one-time setup step and does not require the MCP server to be running.
Supported agents:
| Agent | What gets detected |
|---|---|
| Claude Code | CLI (claude) and/or config at ~/.claude.json |
| Claude Desktop | App config at the platform-specific Claude Desktop path |
| Cursor | CLI (cursor) and/or config at ~/.cursor/mcp.json |
| Codex | CLI (codex) and/or config at ~/.codex/config.toml |
Step 1: Install the MCP entry
From your SolidX project root:
solidctl mcp installThe command:
- Reads your project's API key from
~/.solidx/<project>/mcp.json(created duringsolidctl create-app). - Detects which of the supported agents above are present on your machine.
- Adds a server entry named
solidx-<project>-mcpto each detected agent's MCP config. - Backs up any config file it modifies.
Options:
| Flag | Default | Description |
|---|---|---|
--project <name> | Derived from cwd | Consuming project name (kebab-case) |
--api-key <key> | From mcp.json | Override the API key (must start with sldx_) |
--url <url> | http://localhost:9000/mcp | MCP server URL |
--name <server> | solidx-<project>-mcp | Override the server entry name |
--agents <list> | All detected | Comma-separated subset: claude-code, cursor, codex, claude-desktop |
--dry-run | — | Print planned changes without writing anything |
--force | — | Re-write even when an identical entry already exists |
Examples:
# Preview what would change
solidctl mcp install --dry-run
# Install into Cursor and Codex only
solidctl mcp install --agents cursor,codex
# Use a new API key generated in the admin panel
solidctl mcp install --api-key sldx_...API key
During scaffolding, solidctl create-app writes an admin API key to ~/.solidx/<project>/mcp.json. mcp install reads that key automatically. If you generated a new key in the admin panel (IAM → API Keys), pass it with --api-key.
Step 2: Restart your agent
If Claude Code, Claude Desktop, Cursor, or Codex was already open when you ran mcp install, restart it so it picks up the new MCP server entry. Newly launched agents load the updated config automatically.
Start the MCP server
If your project is already running via solidctl start:dev (the default from the Getting Started guide), the MCP server is already running — start:dev supervises the API, UI, and MCP server together.
You only need to start the MCP server separately if you launched the project with a subset of services, for example:
solidctl start:dev --api # API only
solidctl start:dev --ui # UI onlyIn that case, start the MCP server from your SolidX project root:
solidctl mcp startOptions:
| Flag | Default | Description |
|---|---|---|
-p, --port | 9000 | Listen port |
-H, --host | 0.0.0.0 | Bind address |
--mount-path | /mcp | URL path for the MCP endpoint |
-l, --log-level | INFO | Logging level |
The server listens at http://localhost:9000/mcp by default. Keep it running while your AI client is connected. With the server up, SolidX tools appear in your agent and you can drive the platform from natural language.
Manual MCP configuration
Use these instructions if solidctl mcp install fails, you want to configure a specific agent by hand, or you are using a client that is not supported by the installer.
You need:
- An API key — from
~/.solidx/<project>/mcp.jsonor generated in the admin panel (IAM → API Keys). - The MCP server running — included by default in
solidctl start:dev, or started separately withsolidctl mcp startif you used--apior--uionly.
Default endpoint: http://localhost:9000/mcp
Default server entry name: solidx-<project>-mcp (replace <project> with your project name).
MCP commands
| Command | What it does |
|---|---|
mcp install | Auto-configure Claude Code, Claude Desktop, Cursor, and Codex |
mcp start | Start the MCP server (HTTP) |
Full reference: solidctl Commands
Next Steps
- Drive SolidX from your AI client using the exposed tools.
- Use the built-in agent instead: see Using SolidX AI Agent.
- Go deeper: read the Reference and Recipes.