Connect through MCP

Connect your AI assistant to the Subconscious.ai Rehoboam MCP server to help design a study and inspect experiment results. Start by choosing your client below. Start with the study compatibility matrix to map your business decision to a supported launch or analysis workflow. Rehoboam owns the server and its tool schemas. The complete tool reference is generated from native discovery; the manifest records the source revision and exact schemas.

Connect your client

1. Get your access token

Sign in to Settings and select Get Access Token. Copy the value under Your Access Token into your client's credential field or local secret storage. Keep it out of chat messages, URLs, screenshots, and shared configuration files.

See Authentication for account access details.

2. Add the server

Use this server address, including the trailing slash:

https://api.subconscious.ai/mcp/

The connection uses Streamable HTTP and an Authorization: Bearer YOUR_ACCESS_TOKEN header. The setup examples below use each client's documented configuration format. They do not certify every client version for paid launches.

VS Code

Run MCP: Open User Configuration from the Command Palette. Merge the following entries into your configuration, preserving any existing servers and inputs:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "subconscious-token",
      "description": "Subconscious.ai access token",
      "password": true
    }
  ],
  "servers": {
    "subconscious": {
      "type": "http",
      "url": "https://api.subconscious.ai/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:subconscious-token}"
      }
    }
  }
}

Start the server from the configuration editor. Enter your token when prompted, then enable its tools in agent chat. VS Code configuration reference.

Claude Code

Make your token available as the SUBCONSCIOUS_ACCESS_TOKEN environment variable in the shell that starts Claude Code. Use your local secret manager or a hidden shell prompt; avoid putting the token in shell history.

Merge this entry into your project's .mcp.json:

{
  "mcpServers": {
    "subconscious": {
      "type": "http",
      "url": "https://api.subconscious.ai/mcp/",
      "headers": {
        "Authorization": "Bearer ${SUBCONSCIOUS_ACCESS_TOKEN}"
      }
    }
  }
}

Keep the variable reference as written; do not replace it with the token in the file. Start Claude Code from that shell, approve the project server when asked, and use /mcp to check its connection. The environment variable must be available each time you start the client. Claude Code MCP reference.

Cursor

Merge this entry into your personal ~/.cursor/mcp.json, preserving any existing servers. Replace YOUR_ACCESS_TOKEN locally with the token from Settings.

{
  "mcpServers": {
    "subconscious": {
      "url": "https://api.subconscious.ai/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

This file contains a credential. Keep it private and do not copy it into a project's shared .cursor/mcp.json. Enable the server in Cursor's MCP settings, then open an agent conversation. Cursor MCP configuration.

Other clients

Choose a remote Streamable HTTP connection and enter the server address above. Set the Authorization header to Bearer followed by your access token in the client's private credential settings.

The client must support custom authentication headers. If its setup screen only offers an OAuth sign-in and no way to supply a bearer token, use one of the configurations above. Do not put the token in the server URL.

3. Check the connection

Open your client's MCP tool list. A successful connection shows the Subconscious tools returned by the server. Then try:

List the tools available from Subconscious and explain which ones help me design a study and inspect existing results. Do not start an experiment.

Listing tools does not launch a paid experiment. For a first study, try the example below.

Before launching a paid experiment

The transport is session-aware. Your client must retain the MCP session and support the server's elicitation flow to approve a paid launch. Configuration syntax differs between clients; use the client's remote MCP connection settings. A client that can list tools is not necessarily able to complete launch approval.

Never put an access token in a URL, a research prompt, or a shared notebook. The server derives caller identity from verified authentication; an assistant cannot grant itself access by supplying a user ID.

Start by connecting and listing tools. Discovery does not launch an experiment. The published manifest describes its pinned source; your connected server's tools/list response is the authority for the capabilities available in that session. The older Ghostshell stdio instructions describe a different registry and should not be used to configure this connection.

Troubleshooting

What you see	What to check
Authentication fails	Use the current access token from Settings, include the Bearer prefix, and check that an environment variable or input prompt resolved to a value.
Connection fails or no tools appear	Check the full server address and HTTP transport, enable the server, and reconnect. Inspect your client's MCP status or logs without sharing credentials.
Tools appear but paid launch approval fails	The client must retain the MCP session and support elicitation. Use the browser workflow if your client cannot show the approval request.
A launch was interrupted	Follow the existing run or launch receipt before retrying. See Poll a run.

Follow a study from question to evidence

Stage	Tools	Your decision
Frame the question	check_causality	Is this a sufficiently clear choice question?
Draft the task	generate_attributes_levels, generate_dependent_variable	Are the attributes, levels, and outcome meaningful?
Review a stored design	create_experiment_draft, get_experiment_draft, revise_experiment_draft	Does the reviewed draft match your study brief?
Launch	start_experiment	Do you approve this exact experiment and its cost?
Follow progress	get_experiment_status	Keep the original run identity while it is non-terminal
Inspect results	get_experiment_details, ask_experiment	Are the expected artifacts present and relevant to your question?
Analyze	The analytics tools below	Which contrast answers the decision you planned?

Example 1: design a study before launching

Help me design a study of job-offer preferences for US software engineers. Include annual salary, working arrangement, and commute. Ask me about any consequential missing details. Propose distinct, actionable attributes and exact levels with units; keep salary separate from benefits. Preserve values I supply, explain the assumptions, and show me the draft. Do not start a paid experiment until I have reviewed the design and approved the client's launch confirmation.

Treat generated designs as proposals. Use Design your first study to check population, comparisons, interpretation, and the plan for human validation.

Example 2: inspect an existing study

Help me inspect my completed job-offer study. If your available tools include find_experiments, find my matching studies and ask me to choose if more than one matches; otherwise ask me for the run ID. Verify the run has finished and has the required results. Use get_analytics_metadata to discover exact labels, then use the direct numeric tools to compare attribute importance and two complete offer configurations that I approve. Report sample sizes, units, uncertainty, and source hashes when available. Describe shares as modeled preferences, not observed hiring outcomes. Do not launch a new experiment or call the delegated analyst.

Study discovery, when available, uses a cached list of your owned studies. Check its freshness and coverage before concluding that a study is missing. Confirm the study type before choosing analytics: conjoint calculations require conjoint results and their respondent artifacts.

Direct numeric tools are the default analysis path. The optional ask_analyst tool, or its older ask_experiment alias, delegates interpretation and may incur model inference costs. Use the names advertised by your connected server.

Review the design with your assistant

• Keep one dimension per attribute level: use $14, not $14 with premium support. Use exact values and units instead of ranges.
• Prefer distinct, actionable attributes with realistic, mutually exclusive levels. Rehoboam's starting guidance is 5–7 attributes and 3–4 levels each; adapt the design to the decision rather than adding filler.
• Preserve a supplied design and choice question. Ask about consequential gaps instead of silently replacing the customer's inputs.
• Include a “not offered” level or a “neither” choice only when it represents a real decision option. Review those settings explicitly.
• Review the resolved respondent count before promising subgroup analysis. confidence_level is an output summary, not a control for sample size. Follow the selected tool's sample-size requirements; report unavailable comparisons rather than substituting overall results.

After approval, poll the returned run. A timeout is a reason to retry a read, not to launch again. Keep the run ID, specification hash, approval receipt, and idempotency key. If the client cannot display the launch confirmation, stop and use the browser workflow rather than retrying with new keys.

Review before approving a paid launch

Draft creation and revision support conjoint designs. start_experiment also accepts the direct request shapes described in its schema. A stored draft and a direct request are different inputs; inspect the exact tool definition before constructing a call.

The server asks for confirmation through the MCP client's trusted elicitation flow. An approval sentence inside an assistant message is not that confirmation. Review the displayed experiment, retain its idempotency key and launch receipt, and use the same identity to reconcile an interrupted attempt. Do not invent a new key merely because a response timed out.

The advanced object is a closed, typed set of options. It is not an arbitrary REST passthrough. See the complete input schemas for required keys, defaults, enumerations, nested options, and constraints. Browser, REST, and MCP defaults can differ, so inspect the resolved request you approve.

After launch, poll the original run. in-queue, running, and unknown are non-terminal. A missing provider record does not prove failure. Check for the expected result artifacts even after finished; see Poll a run.

Choose an analysis tool deliberately

Tool	Use it for	Interpretation boundary
get_analytics_metadata	Discover the available attributes, levels, and analyses	Availability is not a finding
get_feature_importance	Compare modeled attribute importance within a design	Importance depends on the levels tested
get_posterior_distribution	Inspect estimated preference variation	Utility variation is not automatically a population confidence interval
get_willingness_to_pay	Inspect a coefficient-based trade-off	Check the returned scale; a ratio is not automatically a currency amount
get_market_share	Compare modeled preference within a submitted choice set	This is not observed market share or a sales forecast
get_factors_affecting_latent_trait	Inspect modeled associations with a specified trait	A model association is not independent human validation of a construct
get_clusters_or_segments	Explore patterns of preference heterogeneity	Exploratory segments need stability checks and a justified interpretation

Use metadata to obtain actual identifiers rather than guessing attribute, level, or segment keys. Inspect each tool's output schema before turning its result into a chart or report. The methodology guide sets out the research validity checks to apply before sharing a conclusion.

Read the same documentation programmatically

• /llms.txt: page index for assistants.
• /llms-full.txt: rendered public documentation text.
• /docs-manifest.json: page digests and documentation revision.
• /mcp/tools.json: complete pinned MCP tool contract.
• /openapi/openapi-manifest.json: REST provenance.

Use the REST API for an application integration that needs explicit HTTP requests and responses. Use the browser workflow when you want to inspect each study-design step visually.