Skip to content

MCP Server Quick Start

This guide covers connecting an AI assistant to the Cognitive3D MCP Server so you can query your XR analytics, chart results, and manage objectives, ExitPolls, and zones in plain language.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to connect to external data sources. The Cognitive3D MCP Server lets you work with your XR analytics through any compatible AI client.

Sign in with your Cognitive3D account

To connect, add the server URL to your AI client and sign in through your browser with your Cognitive3D login. You never copy an API key, and your organization comes from your login.

https://c3d.mcp.cognitive3d.com/mcp
  • Sign-in choices are Continue with SSO (your organization's domain-based single sign-on), Continue with Google, and Continue with Microsoft.
  • You stay signed in. Your client renews access in the background, so there is no periodic re-login prompt.
  • What you can change depends on your role. See Tools that change data.

Claude Desktop and claude.ai

Claude Desktop and claude.ai connect to remote MCP servers directly. You do not need Node.js or a configuration file.

Claude desktop custom connector dialog

  1. Open Settings → Connectors.
  2. Press Add custom connector.
  3. Enter a name, such as Cognitive3D, and the server URL:

    https://c3d.mcp.cognitive3d.com/mcp
    
  4. Save, then press Connect. Your browser opens the Cognitive3D sign-in page.

  5. Choose Continue with SSO, Continue with Google, or Continue with Microsoft, then approve access.
  6. Return to Claude. The connector shows as connected, and the Cognitive3D tools are available in new conversations. You may need to restart Claude Desktop first.

Claude Code

Add the server without credentials:

claude mcp add --transport http cognitive3d https://c3d.mcp.cognitive3d.com/mcp

Then start Claude Code, run /mcp, select cognitive3d, and follow the browser sign-in.

To add Cognitive3D skills to Claude Code, see Claude Code plugins and skills.

Other clients

Any client that supports remote MCP servers with OAuth sign-in can connect the same way. Add the server URL as a remote (HTTP) MCP server, then sign in when the client prompts you. Check your client's documentation for where to add a remote MCP server.

If your client only supports local MCP servers or static headers, connect with an organization API key.

Connect with an organization API key

Signing in is the standard way to connect. Use an organization API key only when browser sign-in is not available, such as in scripts, CI, or clients that only send static headers. Your client sends two headers with every request:

X-API-Key: orgkey-YOUR_ORGANIZATION_API_KEY
X-Org-ID: YOUR_ORG_ID

You need your organization API key (format: orgkey-xxxxx) and your organization ID (numeric).

Finding your credentials

Create and manage organization API keys in the Cognitive3D dashboard under Organization Settings → Manage API Keys.

Your organization ID is in the dashboard URL.

the Organization ID is in the URL

  1. Press the gear icon.
  2. Select Organization Settings.
  3. Find the number after /organizations/ in the URL. That number is your organization ID, 76 in this image.

Claude Code with an organization API key

claude mcp add cognitive3d \
  --transport http \
  https://c3d.mcp.cognitive3d.com/mcp \
  --header "X-API-Key: orgkey-YOUR_ORGANIZATION_API_KEY" \
  --header "X-Org-ID: YOUR_ORG_ID"

Replace orgkey-YOUR_ORGANIZATION_API_KEY with your organization API key and YOUR_ORG_ID with your organization ID.

Claude Desktop with an organization API key

This route proxies through mcp-remote, so it requires Node.js.

  1. Find your Claude Desktop configuration file:

    Platform Path
    macOS ~/Library/Application Support/Claude/claude_desktop_config.json
    Windows %APPDATA%\Claude\claude_desktop_config.json
    Linux ~/.config/Claude/claude_desktop_config.json
  2. Add the following configuration:

    {
      "mcpServers": {
        "cognitive3d": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://c3d.mcp.cognitive3d.com/mcp",
            "--header",
            "X-API-Key:orgkey-YOUR_ORGANIZATION_API_KEY",
            "--header",
            "X-Org-ID:YOUR_ORG_ID"
          ]
        }
      }
    }
    
  3. Replace orgkey-YOUR_ORGANIZATION_API_KEY with your organization API key.

  4. Replace YOUR_ORG_ID with your organization ID.
  5. Restart Claude Desktop.

What you can do

Once connected, ask in plain language. The assistant picks the right tool.

Area What you can ask for
Organization An overview of your organization, its projects, and session trends.
Projects Project details, scenes, and comparisons between projects.
Sessions Sessions for a scene or a participant, with device and platform filters.
Objectives Objective results, and creating, editing, or deleting objectives.
ExitPoll surveys Survey configuration, question sets, hooks, and charted responses.
Zones Zones, shapes, and visit statistics, and creating zones from a description.
Charts Charts of trends, distributions, funnels, heatmaps, and more.

The server also provides reference resources that an assistant can read before it calls a tool. For every tool and whether it changes data, see the tool reference.

Example queries

  • "Show me an overview of my organization."
  • "What are the recent sessions for project X?"
  • "How are the objectives performing in my training application?"
  • "Chart the responses to my end-of-session survey."
  • "Create an objective where users must look at the fire extinguisher and trigger the alarm_pulled event."

Tools that change data

Most tools only read data. A small set creates, edits, or deletes objectives, ExitPoll question sets and hooks, and zones and shapes.

  • Every change is previewed first. The tool describes what will happen and nothing is written until you confirm. The one exception is renaming or re-describing a zone, which applies immediately.
  • Your role decides what you can change. Changes require an organization-admin or project-admin role. A read-only organization API key can view data but cannot change it.
  • Some changes cannot be undone. Deleting an objective removes all of its versions. Read the preview before you confirm.

Troubleshooting

Connection failed

  • If you sign in through your browser, remove the connector or server, add it again, and repeat the sign-in.
  • If you use an organization API key, verify that it starts with orgkey- (not org-) and that your organization ID is numeric.
  • If you use the Claude Desktop configuration file, ensure Node.js is installed and npx is available in your PATH.

No data returned

  • Verify that you have projects and sessions in your Cognitive3D account.
  • Check that your account or organization API key has access to the project.

Authentication errors

  • Use an organization API key, not a developer key or an application key.
  • Ensure there are no extra spaces in your credentials.
  • Use your organization ID, not a project ID.

A change was refused

  • Check that your account has an organization-admin or project-admin role for the project.
  • If you connect with an organization API key, check that the key is not read-only.

intercom If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.