# MCP Server ### What is it The Cognition MCP server is a remote [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://www.cognition.run/privacy). For terms of service, see [cognition.run/terms](https://www.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:** **Documentation:** [docs.cognition.run](https://docs.cognition.run/) **Security vulnerabilities:** If you discover a security issue, please report it to . We will acknowledge receipt within 48 hours. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cognition.run/digging-deeper/mcp-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.