Skip to main content

MCP server

Subconscious.ai ships an MCP server, so an AI assistant can design and run experiments directly. It is the fastest way to try the platform without writing integration code.

Choose an entry point​

  • Use the REST API for an application or service. The OpenAPI document is the contract.
  • Use MCP for a local AI client such as Claude Desktop or Cursor. The tool manifest lists the supported tools and schemas.
  • Use the source repositories when you need to inspect or contribute to the implementation. Rehoboam owns the REST schema. Ghostshell owns the MCP registry.

Agents can start with /llms.txt, read the full public text at /llms-full.txt, and verify source revisions in /docs-manifest.json and /openapi/openapi-manifest.json.

Supported: run locally over stdio​

Use your access token from Settings. Clone Subconscious-ai/ghostshell, create a Python virtual environment, and install the repository:

python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Add this server to your client's MCP configuration. Use absolute paths:

{
  "mcpServers": {
    "subconscious-ai": {
      "command": "/absolute/path/to/ghostshell/venv/bin/python3",
      "args": ["/absolute/path/to/ghostshell/server/main.py"],
      "env": {
        "AUTH0_JWT_TOKEN": "YOUR_TOKEN",
        "API_BASE_URL": "https://api.subconscious.ai"
      }
    }
  }
}

Keep the configuration private because it contains a bearer credential. Restart the client after editing its configuration.

The hosted SSE transport is experimental. It accepts bearer credentials only in the Authorization header. Never put a token in a URL. Hosted setup is not recommended until its credentialed protocol smoke test is complete.

You can verify the supported local protocol without calling a paid tool:

python scripts/smoke_stdio_mcp.py

What you can ask for​

The server exposes the experiment loop as tools, so requests in plain language work:

  • "Run a conjoint experiment on what drives choice of electric vehicles."
  • "What's the status of run a1b2c3d4?"
  • "Show me the AMCEs for that run."

Long-running experiment status is available through the status tools.

The request shape​

The MCP layer takes a deliberately small request: the research question, the experiment type, whether the run is private, and an optional population selection. Anything else goes in an advanced object that passes through to the REST API.

That small surface is a good model for your own integration too: see Run an experiment.

Source​

The server is open at Subconscious-ai/ghostshell, including instructions for running it locally instead of using the hosted endpoint.