MCP Server

What is it

The Cognition MCP server is a remote Model Context Protocol server that connects AI assistants — such as Claude, ChatGPT, Cursor, and others — to your cognition.run account. It allows you to manage experiments, monitor participant sessions, deploy code, and retrieve results directly from a conversational AI interface, without leaving your workflow.

What is it for

The server is designed for researchers who use cognition.run to host jsPsych-based behavioral experiments. Instead of switching between the cognition.run dashboard and your AI assistant, you can:

• Create and configure experiments by describing them in natural language.

• Deploy and update jsPsych source code to a live experiment URL.

• Control data collection: open recruitment, pause it, or set automatic stop rules.

• Monitor participant sessions and review completion status.

• Retrieve trial-level behavioral data for analysis.

• Manage collaborator access and informed consent forms.

• Generate and manage single-use participant links.

The MCP server acts as a hosting and management control plane. It does not write your experiment code for you — your AI assistant does that. The server deploys, hosts, and manages what the assistant produces.

How it works

1. You connect your cognition.run account to an MCP-compatible AI client (see Authentication below).

2. You describe what you want in plain language — for example, "create a new experiment called Stroop Pilot" or "show me how many participants have completed my study."

3. The AI client translates your request into one or more MCP tool calls to the Cognition server.

4. The server executes the operation against your cognition.run account and returns the result.

5. The AI client presents the result in the conversation and can take follow-up actions based on it.

All operations are scoped to your authenticated account. The server only accesses projects you own or that have been shared with you.

Authentication

The Cognition MCP server requires OAuth 2.0 authentication. When you connect for the first time, your AI client will open a browser window where you log in with your existing cognition.run credentials and authorize the connection. No API keys or configuration files are required.

Connecting from Claude (claude.ai or Claude Desktop)

1. Open Settings and go to Connectors.

2. Find "Cognition" in the directory, or add a custom connector with the URL: https://www.cognition.run/mcp

3. Click Connect. A browser window opens with the cognition.run login page.

4. Log in and authorize the connection.

5. The connector is now available in your conversations.

Connecting from ChatGPT

1. Go to Settings, then Apps & Connectors, then Advanced.

2. Enable Developer Mode (requires Pro, Business, Enterprise, or Edu plan).

3. Create a new connector with the URL: https://www.cognition.run/mcp

4. Complete the OAuth flow in the browser when prompted.

Connecting from Claude Code

1. Run: claude mcp add cognition --transport http https://www.cognition.run/mcp

2. Complete the OAuth flow when prompted in your browser.

Revoking access

You can revoke the MCP connection at any time from your cognition.run account settings under "Connected Applications." Revoking access immediately invalidates all tokens. You will need to re-authorize if you want to reconnect.

Available tools

Experiments

Tool	Description	Access
list-tasks	List all your experiments, including shared ones.	Read-only
create-task	Create a new experiment. Accepts name, language, number of between-subject conditions, IP storage preference, and email notification settings.	Write
get-task	View an experiment's configuration, participant count, and collection status.	Read-only
update-task	Modify experiment settings: name, language, conditions, jsPsych library version, IP storage, email notifications, and PHI mode.	Write
delete-task	Permanently delete an experiment and all its collected data.	Destructive

Source code

Tool	Description	Access
get-source-code	Read the jsPsych code that defines the experiment's trial structure and stimuli.	Read-only
update-source-code	Deploy new or updated jsPsych source code to the experiment.	Write

Data collection

Tool	Description	Access
get-data-collection	Check whether an experiment is open for participants and view stop rules.	Read-only
update-data-collection	Open or close recruitment. Supports immediate stop, stop at a specific date, or stop after a target number of completions.	Write

Participant sessions

Tool	Description	Access
list-runs	Browse participant sessions with completion status and timestamps. Supports pagination.	Read-only
get-run	Inspect a single session: status, consent, errors, and metadata.	Read-only
get-run-data	Retrieve trial-level behavioral data from a participant session. Subject to PHI mode restrictions (see Privacy section below).	Read-only
delete-run	Permanently delete a session and its data.	Destructive

Participant links

Tool	Description	Access
list-links	Browse single-use participant links and their consumption status. Supports pagination.	Read-only
create-links	Generate 1 to 500 single-use links with sequential or random token codes.	Write
delete-link	Delete a single participant link.	Destructive
delete-all-links	Delete all participant links for an experiment.	Destructive

Informed consent

Tool	Description	Access
get-consent	Read the consent form shown to participants before the experiment.	Read-only
update-consent	Write or update the consent form. Accepts plain text or Markdown (minimum 50 characters). Optionally set a redirect URL for participants who decline.	Write
remove-consent	Remove the consent requirement from the experiment.	Destructive

Collaborators

Tool	Description	Access
list-collaborators	See who has access to an experiment and their roles.	Read-only
add-collaborator	Invite a researcher by email as viewer, editor, or owner.	Write
update-collaborator-role	Change a collaborator's role.	Write
remove-collaborator	Revoke a collaborator's access.	Destructive

Usage examples

Example 1: Create and deploy an experiment

Prompt: "Create a new experiment called 'Stroop Pilot', set the language to English, and deploy a basic Stroop task with 20 congruent and 20 incongruent trials."

What happens: The assistant calls create-task with the name and language, then generates jsPsych code for the Stroop task, and calls update-source-code to deploy it. The experiment is immediately accessible at its public URL.

Example 2: Monitor recruitment progress

Prompt: "How many participants have completed my Flanker Task study? Set it to stop automatically at 50 completions."

What happens: The assistant calls get-task to retrieve the current participant count, then calls update-data-collection with mode stop-at-runs and a target of 50.

Example 3: Retrieve and analyze data

Prompt: "Get the data from participant 12 in my Stroop Pilot and calculate mean reaction times by condition."

What happens: The assistant calls get-run-data for the specified session, receives the trial-level data, and writes an analysis script to compute the summary statistics.

Privacy and Protected Health Information (HIPAA)

Cognition.run is used by researchers who may collect sensitive health-related data from experiment participants. The MCP server includes safeguards to prevent unintended exposure of Protected Health Information (PHI) through AI assistant connections.

PHI mode

Every experiment has a phi_mode setting with three states:

Not declared (default). When the MCP server receives a request to access participant data for a project that has not declared its PHI status, it returns an error prompting the researcher to classify the project. The AI assistant will ask you whether the experiment collects health-related information linked to identifiable participants. Your declaration is recorded with a timestamp.

PHI mode off (false). The researcher has declared that the experiment does not collect PHI. Participant data is accessible through the MCP server normally. This is appropriate for most cognitive psychology experiments that use anonymous participant codes and collect only behavioral measures such as reaction times and accuracy.

PHI mode on (true). The researcher has declared that the experiment collects PHI. Participant data is not accessible through the MCP server — neither as raw data nor as a downloadable URL. The researcher must download data directly through their authenticated browser session on cognition.run. The AI assistant can still access the data schema (column names, types, and aggregate statistics) to help write analysis scripts, but never the raw values.

PHI mode can be set via update-task with the phi_mode parameter, or through the cognition.run dashboard. Once set to true, it can only be changed back to false from the dashboard — not via MCP. This prevents accidental or automated declassification.

Why this matters

When you connect an AI assistant via MCP, data returned by the server enters the assistant provider's infrastructure (Anthropic, OpenAI, etc.). Cognition.run does not have Business Associate Agreements (BAAs) with these providers. Sending PHI through an MCP connection is not HIPAA-compliant. The phi_mode safeguard exists to prevent this from happening inadvertently.

Researcher responsibility

The researcher is solely responsible for accurately classifying whether an experiment contains PHI. Cognition.run provides the declaration mechanism as a reasonable safeguard but does not independently verify the nature of collected data.

For the full privacy policy, see cognition.run/privacy. For terms of service, see cognition.run/terms.

Troubleshooting

OAuth flow does not complete. Make sure you are using a supported AI client (Claude, ChatGPT with Developer Mode, Claude Code, or another MCP-compatible client). Check that your browser allows pop-ups from your AI client's domain. If the flow times out, try disconnecting and reconnecting.

Tool calls return "unauthorized" errors. Your token may have expired or been revoked. Disconnect the connector in your AI client's settings and reconnect to obtain a fresh token.

"PHI mode not declared" error when accessing data. The experiment has not been classified yet. Tell your AI assistant whether the experiment collects health information linked to identifiable participants. The assistant will set the appropriate mode and retry.

Data access blocked on a PHI-protected project. This is working as intended. Download the data directly from cognition.run in your browser. You can ask the AI assistant to write analysis scripts based on the data schema without exposing the raw values.

Tool call returns a large error or no data. Check that the experiment ID and run ID are correct. Use list-tasks and list-runs to verify available resources. If the problem persists, contact support.

Experiment code fails after deployment. Use get-source-code to inspect what was deployed. The MCP server deploys code as-is; it does not validate jsPsych syntax. Test your experiment in a browser after deployment by visiting its public URL.

Support

For technical issues, account questions, or security concerns:

Email: [email protected]

Documentation: docs.cognition.run

Security vulnerabilities: If you discover a security issue, please report it to [email protected]. We will acknowledge receipt within 48 hours.