User Intuition MCP Server (Node)

An MCP (Model Context Protocol) server that exposes the User Intuition research platform to AI agents. Build and run live interview studies, recruit participants from the panel, analyze transcripts, and generate reports.

Supports stdio (CLI) and Streamable HTTP transports. Both transports expose the same tools, catalog resources, and public workflow prompts. Internal planning templates are never exposed. Models and clients that support remote Streamable HTTP with OAuth should use the hosted OAuth path first. Stdio remains available for local clients that need it. Hosted /mcp endpoints accept POST; unsupported GET and DELETE return 405.

ChatGPT / Codex / OAuth-capable clients
        ↓  (MCP over Streamable HTTP + OAuth)
   Hosted User Intuition MCP Server
        ↓  (REST HTTP + account token)
   User Intuition Backend API

Claude Desktop / Cursor / Claude Code / VS Code
        ↓  (MCP over stdio)
   Local User Intuition MCP Server
        ↓  (REST HTTP + Bearer token)
   User Intuition Backend API

Quick Start

Hosted OAuth (recommended first)

Connect compatible clients to:

https://mcp.userintuition.ai/mcp

The client discovers OAuth automatically. API keys also work with hosted MCP, stdio, the public REST API, and the CLI.

Smaller tool profiles

Use the core endpoint for the common study → interview → report workflow. It exposes 61 tools, including organization selection, and omits webhook, feasibility, and external-panel administration. The read-only endpoint exposes 31 read tools, including research search and account inspection, and cannot perform writes. Both profiles have their own OAuth protected-resource metadata; connect and authorize each endpoint separately.

https://mcp.userintuition.ai/core/mcp
https://mcp.userintuition.ai/read-only/mcp

The compact endpoint keeps the full research workflow but groups 15 less common webhook, feasibility, and external-panel operations into six tools. Each grouped call selects an operation and supplies that operation's original arguments. Read actions stay separate from writes; grouped writes carry conservative destructive hints so hosts can request confirmation. Connect it with its own OAuth authorization, or use an API key with the required scopes.

https://mcp.userintuition.ai/compact/mcp

The existing /mcp endpoint keeps all 79 tools for integrations that use the full API. Local stdio clients can select --profile core or --profile read-only or --profile compact; the default remains full. Resource and prompt support is available on the smaller profiles too.

Measured with npm run measure:tools against this version's complete tools/list payload (UTF-8 bytes; the token estimate uses four bytes per token, so a host's actual count will differ):

| Profile | Tools | Payload bytes | Approx. tokens | |---|---:|---:|---:| | Full | 79 | 168,033 | 42,008 | | Core | 60 | 130,899 | 32,725 | | Read-only | 31 | 77,801 | 19,450 | | Compact | 70 | 153,342 | 38,336 | | Directory | 8 | 31,760 | 7,940 |

The compact profile uses inspect_webhooks, manage_webhook, remove_webhook, inspect_feasibility, manage_feasibility, get_external_panel, and manage_external_panel. Grouped tools use the corresponding full-profile tool name as their operation value. Version 0.17.0 replaces three action-dispatch tools at /mcp with dedicated operations: manage_research_session becomes eight session and source tools, run_research_analysis becomes start/resume/cancel tools, and manage_research_output becomes rename/delete tools. The underlying operations remain available. launch_panel opens the human approval App before any paid request. CI runs npm run measure:tools:check against byte budgets for every profile; the token column is an estimate, not a guarantee of host context usage.

Claude directory connector

The Claude directory listing uses the complete research workflow:

https://mcp.userintuition.ai/mcp

Sign in with User Intuition OAuth. The full endpoint exposes all 79 tools, including study design, recruitment estimates, paid Panel launch with separate human approval, fielding, reports, research analysis, and authorized participant or account operations. A paid Panel launch can consume credits or place a card hold. Tool access follows the signed-in account's permissions and granted scopes.

For directory review, use a dedicated User Intuition account with sample studies, completed interviews, and reports. The reviewer should connect to the full endpoint with OAuth, then try these prompts:

1. “List my studies that have reports.”
2. “What did participants say about onboarding in study <study_id>? Show the interview evidence.”
3. “Create a draft study for an audience I choose, then show me the saved plan and a Panel estimate before any launch.”

The separate /directory/mcp profile remains available to custom clients that explicitly want an eight-tool, read-only research surface. It is not the endpoint used by the Claude directory listing. The Claude directory connector guide explains setup and approval boundaries.

CLI

The package also exposes 75 MCP tools as direct shell commands. Panel launch requires an MCP App host and is unavailable through the direct CLI. Sign in with browser OAuth, then call a tool:

npm install -g @userintuition-ai/mcp
userintuition-mcp login
userintuition-mcp list_studies

Create and save an organization API key when you also need local stdio or CI access:

userintuition-mcp api-key create --name "My laptop"

The raw key is shown once and stored with the OAuth credentials in a private local file. USERINTUITION_API_KEY remains supported and takes precedence over saved credentials. Run userintuition-mcp auth status to inspect local configuration or userintuition-mcp auth logout to remove it.

ChatGPT

Enable developer mode under Settings → Apps & Connectors → Advanced, create a connector using https://mcp.userintuition.ai/mcp, and complete OAuth. Start a new chat after connecting so ChatGPT loads the current tool catalog.

Codex

codex mcp add userintuition --url https://mcp.userintuition.ai/mcp
codex mcp login userintuition

The add command may start OAuth immediately. Complete that flow and use the separate login command only if authorization remains pending. Restart Codex or open a new task afterward.

Other compatible clients

Add a Streamable HTTP MCP server using https://mcp.userintuition.ai/mcp, then complete the discovered OAuth flow.

Stdio setup

1. Get an API Key

Either use the CLI flow above or sign up at app.userintuition.ai and generate an API key from Settings > API Keys.

Users can belong to multiple organizations. Call list_organizations, optionally searching by organization name, active owner name, or owner email, then supply organization_id on subsequent tools to choose the workspace for reads, writes, billing, and audit context. Call get_account with the same ID to verify the selected workspace before a paid action. Only active memberships in the current app are available to ordinary users; platform administrators have app-wide access. Without an explicit selection, the credential's default organization is used (platform administrators have global research read access). API-key scopes still apply in every selected organization. API keys have no spending cap; paid actions still require authorization, approval, and the selected organization's billing.

2. Connect Your Client

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "userintuition": {
      "command": "npx",
      "args": ["-y", "@userintuition-ai/mcp"],
      "env": {
        "USERINTUITION_API_KEY": "ui_sk_your_key_here"
      }
    }
  }
}

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "userintuition": {
      "command": "npx",
      "args": ["-y", "@userintuition-ai/mcp"],
      "env": {
        "USERINTUITION_API_KEY": "ui_sk_your_key_here"
      }
    }
  }
}

Claude Code:

claude mcp add userintuition -- npx -y @userintuition-ai/mcp

Then set USERINTUITION_API_KEY in your environment.

Public API tool results place complete typed JSON in structuredContent.result; supplemental tools use structuredContent directly. MCP also returns the complete JSON in text content for model tool chaining. view_research_answer returns a readable answer and quotation labels alongside its structured result and App metadata.

VS Code — .vscode/settings.json:

{
  "mcp.servers": {
    "userintuition": {
      "command": "npx",
      "args": ["-y", "@userintuition-ai/mcp"],
      "env": {
        "USERINTUITION_API_KEY": "ui_sk_your_key_here"
      }
    }
  }
}

Verify

Ask the agent to call get_account. A successful account-scoped response confirms authentication; merely seeing tool names does not. The current catalog contains 79 tools, including answer_research, queue_customize_study, customize_study, and review_study, and excluding ask_humans.

Tools

The MCP server registers 79 tools over stdio and Streamable HTTP. The public API tools cover studies, participants, interviews, external panels, paid panels, and webhooks; account, targeting, and usage tools complete the surface. Read the five configuration catalogs through MCP resources. review_study opens a read-only MCP App for the saved plan and fielding progress. launch_panel opens a separate MCP App showing the saved plan and current estimate. For clients advertising MCP App support, its human Approve and launch panel button sends the paid request through the App-only approve_panel_launch tool. The MCP server rechecks the plan and estimate before launch. Clients without MCP App support receive a chat review from launch_panel containing the saved plan, current estimate, and a short-lived chat_approval_nonce. The model must show the complete plan and a readable estimate (cost, balance, credit deficit, reward, card hold, timeline, expiry and assumptions), then ask the human to confirm this launch. Only after explicit confirmation may it call launch_panel again with the same inputs, the nonce and human_confirmed: true. The server binds the review to the credential, organization, saved study version and estimate, consumes it once, and checks whether the study is already fielding. A changed or expired review requires fresh human confirmation. After an uncertain launch response, check get_study before taking any further action; do not request a new review merely to retry the launch.

Chat confirmation is enforced by the model: the server cannot independently verify who typed the confirmation. Clients advertising App support cannot submit via the chat path. The REST API and SDKs retain their existing behavior.

Intelligence Hub sessions and Studio

Use the organization-scoped public Hub API through these tools. Create a session, add/sync studies or upload sources, then chat or generate outputs. File Search retrieves relevant evidence; reports and PowerPoints reuse saved findings. You do not need to start exhaustive analysis before creating an output.

| Tool | Description | |---|---| | create_research_session | Create a Hub session with a retry key | | rename_research_session / delete_research_session | Rename or delete a selected Hub session | | sync_research_study / remove_research_study / remove_research_source | Add or remove individual session sources | | add_all_research_studies / clear_research_sources | Legacy bulk study selection or source removal | | inspect_research_session | List sessions, sources, chat history, outputs; read a session, output, or job | | upload_research_source | Upload external evidence as base64 file contents (10 MB decoded maximum) | | chat_research_session | Synchronous chat; returns a durable job when the wait expires | | queue_research_chat | Queue chat immediately; shares retry keys with synchronous chat | | generate_research_output | Queue a report, native PowerPoint, or saved Highlights video | | edit_research_output | Prompt an in-place report or PowerPoint edit; retains the output ID | | rename_research_output / delete_research_output | Rename or delete an output | | upload_research_template | Upload a report or presentation template (5 MB maximum) | | download_research_output | Download Markdown/PPTX/PDF bytes or get a private Highlights video link | | start_research_analysis / resume_research_analysis / cancel_research_analysis | Start, resume, or cancel an advanced analysis run | | get_research_analysis | Inspect canonical evidence, coverage and legacy run history | | queue_research_deliverable | Advanced run-bound presentation, clip, reel or default-report video export | | get_research_deliverable | Poll a legacy export and obtain its private download link | | cancel_research_deliverable | Cancel a legacy export job |

Use inspect_research_session with view: "job", session_id, and the returned job_id to poll chat, preparation, generation and edits. On success, read the answer/references or the returned output_id. Use parent_job_id for a chat follow-up. Preserve idempotency_key and the exact input on retries. A sync wait expiring never cancels or duplicates the backend job. Native Tasks remain available for the existing low-level queue_research_deliverable tool; the new session tools use explicit durable job polling on both transports.

Read outputs before editing. Edits publish in place after success; default reports are read-only. Highlights are generated once per default-report revision, with learning-goal chapters and the report's verified quotations. Original audio is used when available; chat-only studies have no artificial narration.

Uploads accept file_name and data_base64, never server-local paths or arbitrary URLs. The host must supply an attachment's bytes. Downloads return structured filename, mime_type, data_base64 and size_bytes (64 MB transfer maximum), or a short-lived download_url for video. Decode file bytes to a local artifact; do not display base64 to the human. Source access is rechecked on every read.

These tools are available on full, core and compact profiles; read-only includes only the four inspectors/download tools. The eight-tool directory profile remains unchanged. Legacy report-slide and run-based tools remain compatible. Integration requires backend PR #794; no npm release is implied by this branch.

Studies and research

| Tool | Description | |------|-------------| | list_studies | List your studies | | create_study | Create a new study | | customize_study | Run one resumable turn through the dashboard's Customize Plan chat | | queue_customize_study | Queue a planning turn and receive a durable job ID; native images use customize_study | | get_customize_study_job | Poll a queued planning turn until it succeeds or fails | | get_study | Fetch the full study (call before a write) | | review_study | Open the saved plan and fielding progress in a read-only MCP App | | update_study | PATCH ordinary study metadata; Customize Plan owns plan/audience/assets | | delete_study | Delete a study | | estimate_panel | Preview panel cost and timing before a paid launch | | launch_panel | Open the MCP App for human review of the saved plan and current estimate; does not spend | | approve_panel_launch | App-only button action that rechecks and launches one paid panel cycle | | pause_study | Pause while preserving panel progress and reward hold | | resume_study | Resume preserved panel recruitment | | stop_study | End panel recruitment and settle/release its hold | | generate_report | Queue a fresh report and return a job ID | | get_report_job | Poll report generation status | | queue_report_slides | Queue an editable PowerPoint export; text PII masking defaults on | | get_report_slide_job | Poll the deck export and receive a short-lived private download URL | | get_fielding_progress | Read completions, target, quality mix, and expected finish | | get_study_report | Get the latest structured findings, evidence coverage, citations, count, and stale status | | search_research | Search indexed studies and return only canonical Study/Report API JSON | | answer_research | Answer across selected studies with citations to accessible canonical research records |

External panels (4)

| Tool | Description | |------|-------------| | get_external_panel | Read the provider entry link and outcome redirects for a BYOP study | | configure_external_panel | Create or replace the external-panel bridge for a BYOP study | | regenerate_external_panel_token | Invalidate the old entry link and issue a new one | | delete_external_panel | Disable the external-panel entry link |

Account (1)

| Tool | Description | |------|-------------| | get_account | Read effective workspace, role, available credits, payment readiness, and incentive limits |

Participants (7)

| Tool | Description | |------|-------------| | list_participants | List BYOP invitations by study or email, with status and personal link | | create_participants | Queue 1–100 unique participants and return a job ID | | get_participant_job | Poll the participant batch before listing invitations | | get_participant | Fetch one participant | | update_participant | Update a participant email | | delete_participant | Soft-delete a BYOP invitation | | send_participant_reward | Send the configured BYOP incentive |

Interviews (3)

| Tool | Description | |------|-------------| | list_interviews | List lightweight interviews by study, status, or quality | | get_interview | Fetch messages, recording links, and screener responses | | delete_interview | Soft-delete an interview |

Panel feasibility (4)

| Tool | Description | |------|-------------| | submit_feasibility_request | Request review for low-incidence or specialized audiences | | list_feasibility_requests | List account requests newest-first | | get_feasibility_request | Fetch one request and its status/estimate | | cancel_feasibility_request | Withdraw a pending feasibility request |

Webhooks (8)

| Tool | Description | |------|-------------| | create_webhook | Create an account or study event webhook | | delete_webhook | Deprecated URL form; use delete_webhook_by_id | | list_webhooks | List registered webhooks | | get_webhook | Inspect one webhook without revealing its secret | | delete_webhook_by_id | Delete one webhook by ID | | rotate_webhook_secret | Replace a signing secret | | test_webhook | Send a data-free signed test event | | list_webhook_deliveries | Inspect delivery attempts |

Targeting catalog (1)

| Tool | Description | |------|-------------| | list_targeting_attributes | Search panel targeting qualifications |

Supplemental interview administration (1)

| Tool | Description | |------|-------------| | get_interview_usage_stats | Aggregate interview usage over a date range |

Catalog resources and workflow prompts

Clients that support MCP resources can list and read these authenticated, live catalogs:

| Resource URI | Content | |--------------|---------| | userintuition://catalog/languages | Supported interview languages | | userintuition://catalog/modes | Interview formats | | userintuition://catalog/study-types | Public study-type template metadata | | userintuition://catalog/study-types/{slug} | One template's public details | | userintuition://catalog/voices | Public interviewer choices | | userintuition://catalog/panel-countries | Supported panel country/language combinations |

The plan_research_study and review_fielding prompts contain public workflow guidance. Clients without resource support can use the equivalent authenticated HTTP catalog endpoints or the published docs; the backend still validates every country and language on writes.

The full MCP server also lists attachable userintuition://study/{study_id} and userintuition://report/{study_id} resources for recent owned research. Read userintuition://report/{study_id}/{view} for one report section. These use the public API with the current credential and never expose the full report as one resource. See the research resource guide for views and size limits.

Durable MCP Tasks

The hosted full and core profiles advertise io.modelcontextprotocol/tasks through 2026-07-28 server/discover. A client that declares the extension on a tools/call receives a task handle for customize_study without a native concept image, queue_customize_study, or generate_report. Poll tasks/get using its taskId. On completion, customize_study returns its planning turn; the queued customization and report tools return their completed job records. Call get_study for the full saved plan or get_study_report for report contents. Paid Panel launch requires human App approval or, for clients without Apps, explicit human chat confirmation; BYOP participant creation requires approval of the saved plan. Native concept images continue through the synchronous customize_study call.

Task handles persist for 24 hours in the hosted Redis store and can be resumed across MCP replicas. Each tasks/get, tasks/update, and tasks/cancel request rechecks backend study or job access. The backend jobs do not request in-task input, so tasks/update acknowledges responses without changing the job. The backend has no cancellation endpoint: tasks/cancel acknowledges the request, but the job may still finish. Clients without the Tasks extension continue to receive the existing job response and can use get_customize_study_job or get_report_job.

Live research events

Clients using the MCP 2026-07-28 protocol can open subscriptions/listen for userintuition://study/{study_id}, userintuition://report/{study_id}, or userintuition://events/{study_id}. The hosted server checks access to each study before accepting the stream. On study.completed or report.ready, it sends notifications/resources/updated for the affected resources. Read the events resource to get the event ID, type, study ID, and data in the same envelope used by webhooks. These are notifications of a changed resource, not a replacement for webhook delivery. The events resource retains the latest 100 envelopes for 24 hours.

Hosted event delivery uses the backend's MCP_EVENT_REDIS_URL and the MCP service's existing REDIS_URL. Those URLs must point to the same Redis instance. Without MCP_EVENT_REDIS_URL on the backend, webhooks still work and no live events are published. Without REDIS_URL on the MCP service, event resources are unavailable. Clients should reconnect a listen stream after it closes; the default maximum lifetime is 25 minutes (LISTEN_STREAM_MAX_MS, at most 60 minutes). MAX_LISTEN_SUBSCRIPTIONS limits simultaneous streams per MCP endpoint and replica (default 200). Older MCP clients can keep using the existing tools and webhooks.

Hosted MCP requests have an IP limit before authentication and a credential limit after authentication. Both default to 120 requests per minute per replica; set MCP_CREDENTIAL_RATE_LIMIT to change the credential limit. The backend also enforces its Redis-backed API-key limits on public API calls made by tools.

Study-Creation Playbook

The server's compact instructions field carries critical workflow rules within clients' instruction limits. Each relevant tool description carries its own step-specific rules; the full playbook is in the docs. Highlights:

• Customize Plan owns study design: create a metadata draft, then pass the user's natural-language brief to customize_study. The backend uses the same planning prompts and tools as the dashboard.
• Resumable confirmations: when customize_study returns response_type="question", relay it to the user and send their answer in the next call.
• Pre-launch plan review: after customization, fetch and return the complete persisted study plan for the user to review. Apply requested revisions through customize_study and return the revised plan. The launch_panel MCP App obtains human approval for the saved plan and current estimate in one action; clients without Apps must obtain explicit human chat confirmation for the returned review; obtain explicit approval of the current plan before BYOP participant creation.
• Study defaults: ask the user for recruitment method before create_study; unless they request otherwise, studies default to a voice interview in English with Elliot.
• Concept tests: create with study_type="concept-test", then send an accessible native attachment through customize_study.concept_image, or include a publicly downloadable image URL in the message. Include its label, stimulus context, audience, and goals. The backend validates, stores, and attaches the image.
• Prototype tests: create with study_type="prototype-test"; it uses the default voice format or an explicitly requested video format. Then send the prototype URL, label, intended tasks, audience, and goals through customize_study. The backend validates and attaches the link; prototype tests cannot use chat.
• Read before write: use get_study before metadata updates and after customization; use get_participant before a participant update.
• Panel lifecycle: pause a fielding study before editing if recruitment should continue; stop it if recruitment is finished.
• Audience and screeners: send the user's audience description to customize_study; the backend checks canonical targeting attributes before creating custom screeners.
• Concept links and images: request additions, replacements, or removals through customize_study. The backend owns safety checks, storage, IDs, mode compatibility, and plan markers.
• Public study metadata: interview_format is voice, chat, or video; the voice configuration remains male or female for every format, including chat.
• Lifecycle language: provisioned means interviews can run; it does not mean participants were invited or Panel fielding was launched.
• Study links: after provisioning, share dashboard_url (researcher management) and study_link (the live participant interview). study_link is not a test/preview URL; the public API does not expose a separate researcher preview.
• Batch participants: participant creation takes 1–100 unique emails; incentives are BYOP-only.

Tool annotations (destructiveHint, idempotentHint, etc.) are documented per-tool in tool-hint-justifications.json.

Installation

Zero-install (recommended)

npx -y @userintuition-ai/mcp

Global install

npm install -g @userintuition-ai/mcp
userintuition-mcp

From source

git clone <repo-url>
cd userintuition-mcpserver-ts
npm install
npm run build
node dist/index.js

Configuration

Stdio Mode (default)

| Variable | Required | Description | |----------|----------|-------------| | USERINTUITION_API_KEY | No | API key override (ui_sk_...). Stdio also reads the key saved by api-key create. | | USERINTUITION_CONFIG_DIR | No | Override the directory containing CLI credentials.json. | | USERINTUITION_OAUTH_ISSUER_URL | No | Override CLI OAuth discovery (defaults to https://mcp.userintuition.ai). | | BACKEND_URL | No | Backend API URL (defaults to https://api.userintuition.ai) | | APP_URL | No | Dashboard URL (defaults to https://app.userintuition.ai) |

HTTP Mode (for hosted OAuth)

Run with --transport streamable-http:

node dist/index.js --transport streamable-http

The hosted service needs its account integration configured. Set SERVER_URL to its public HTTPS URL. HOST and PORT control the listener. REDIS_URL is required for shared OAuth storage whenever SERVER_URL is public or NODE_ENV=production; in-memory storage is only for local development.

ChatGPT Setup

1. Settings > Apps & Connectors > Advanced > Enable Developer Mode
2. Settings > Connectors > Create:
   • Name: User Intuition
   • MCP Server URL: https://<your-deployed-url>/mcp
   • Authentication: OAuth (auto-discovered)

Running Locally

# Stdio mode (default)
npm run dev

# HTTP mode
npm run dev:http

# Production builds
npm run build
npm start                # stdio
npm run start:http

Inspecting with MCP Inspector

MCP Inspector lets you browse tools and test them interactively.

Stdio mode:

USERINTUITION_API_KEY=ui_sk_your_key_here npx @modelcontextprotocol/inspector node dist/index.js

HTTP mode:

npm run start:http
npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp

Deployment

Docker (HTTP mode)

docker build -t userintuition-mcp .
docker run -p 8000:8000 --env-file .env userintuition-mcp

Set SERVER_URL to your public HTTPS URL. Deploy to a container platform with persistent access to the required environment variables.

Optional hosted-service analytics

The User Intuition hosted service can enable anonymous tool-call counters for authenticated HTTP requests. This is disabled by default. It is disabled by default and always disabled for stdio/npm clients.

mcp_tool_completed records the registered tool name, transport, outcome (success, tool_error, or exception), duration, and an internal-test flag. It does not record arguments, results, exception text, account/study identifiers, credentials, or visitor IPs; no person profile is created. Events count calls, not customers, and a successful call does not necessarily mean a study launched or an interview completed. Direct REST and npm/stdio traffic are outside scope. Set X-UI-Analytics-Test: 1 on verification requests and exclude those events in dashboards. Clear MCP_ANALYTICS_ENABLED to disable capture immediately.

Testing

npm install
npm test
npm run test:coverage

Project Structure

├── src/
│   ├── index.ts                # CLI entry point (transport selection)
│   ├── server.ts               # McpServer factory + study-creation playbook instructions
│   ├── tools.ts                # Thin re-export of tools/index.ts
│   ├── client.ts               # Thin re-export of clients/
│   ├── auth.ts                 # OAuth integration (HTTP only)
│   ├── auth-context.ts         # AsyncLocalStorage for token forwarding
│   ├── http.ts                 # Express app with OAuth + /mcp
│   ├── store.ts                # Token storage (InMemory + Redis)
│   ├── config.ts               # Environment variable settings
│   ├── tools/
│   │   ├── index.ts            # registerTools(mcp) — public API surface
│   │   ├── _shared.ts          # getToken, textResult, errorResult
│   │   ├── public-api.ts       # public API tools and input schemas
│   │   ├── output-schemas.ts   # compact public output contracts
│   │   ├── account-public.ts   # account context tool
│   │   └── usage.ts            # interview usage tool
│   ├── resources/catalog.ts   # authenticated catalog resources
│   ├── resources/research.ts  # attachable study and report resources
│   ├── prompts/research.ts     # public workflow prompts
│   └── clients/
│       ├── _base.ts            # fetchJson, HttpStatusError, authHeaders
│       ├── public-api.ts       # /api/public/v1 HTTP client
│       └── research.ts         # legacy dashboard HTTP client
├── tests/                      # vitest + msw, one file per domain
├── tool-hint-justifications.json
├── server.json                 # official MCP registry metadata
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── Dockerfile

Release publishing

The v* tag workflow publishes the npm package, then publishes server.json to the official MCP Registry and refreshes the Smithery external-server release. The registry and Smithery sync workflows can also be run on demand without republishing npm. The tag and server.json package entry must match package.json. The top-level server.json version is an independent Registry metadata version: increment it above the Registry's latest version whenever publishing new metadata. This is necessary because an older Registry entry used version 1.1.0 before the npm package reached 0.12.x; the Registry picks the latest entry by version. The registry publisher authenticates the ai.userintuition namespace with the userintuition.ai DNS proof record and the matching Ed25519 private key in the MCP_PRIVATE_KEY repository secret. See the official DNS authentication instructions for key setup and rotation. The Smithery job uses the SMITHERY_API_KEY repository secret to update listing metadata from server.json and scan the live MCP endpoint. The public /.well-known/mcp/server-card.json exposes the same tool, resource, and prompt definitions to Smithery without repeatedly authorizing a test account. Both jobs fail visibly if their required secret is missing or the directory rejects the update.

Glama imports listing text and technical connection details from the official MCP Registry and periodically checks the hosted endpoint through its OAuth test profile. Its "Use Glama listing details as the source of truth" setting must remain off for the name, description, and URL to follow server.json; categories and thumbnail remain managed on Glama. OpenAI continuously reviews compatible live MCP tool changes after the plugin is published; listing and skills changes still require a new reviewed plugin version. Claude checks its tracked plugin branch on a schedule; publishing behavior depends on the directory's review and auto-publish settings. PulseMCP is not accepting submissions at present.

Research workflows and examples

Start at the agent homepage for study execution, source-linked results, and research search. The public TypeScript examples run with fictional fixtures by default and include a release compatibility checklist. Use the current catalog for exact tool names and schemas.

Tool-size diagnostics

Run npm run measure:tools -- --breakdown to compare profile wire bytes, description bytes, input/output schema bytes and the five largest tools. The displayed token estimate divides UTF-8 bytes by four; it is not a measurement of what a particular host sends to its model. Hosts may omit output schemas, reformat input schemas, or load tools on demand. Measure the host's actual context before choosing a schema reduction. Use core for study workflows and directory for research-library discovery; keep the existing version, quote and approval checks in all paid workflows.

Study answers with reference cards

Use chat_research_session or queue_research_chat for findings, feedback and comparisons. Resolve studies, create or reuse the selected Hub session, and attach only missing requested sources. Reuse the session and last completed parent_job_id for follow-ups without resyncing unchanged studies.

| Tool | Description | | --- | --- | | view_research_answer | Reopen a Hub answer with clickable citations, exact quote context and available original recordings; read-only and authorized on each request. |

MCP Apps hosts display citations inside the answer App. Other hosts receive readable answers, quotations and a dashboard link. No host-specific citation UI is assumed. Plan edits continue through customize_study.

For hosted deployments using private networking, BACKEND_URL is the server-to-server API address. PUBLIC_BACKEND_URL is the browser-accessible API origin allowed to serve original recordings inside MCP reference cards. It defaults to the production API (or staging API for the sandbox issuer) when the backend uses Railway's internal network. Local/public backend URLs are reused by default. Never set the public recording origin to a private Railway hostname.

Documentation inventory

Run npm run docs:surface --silent to export tool names, profile counts and payload sizes, CLI commands, resources, and prompts from registration. The export makes no backend requests. Commit source changes before copying the JSON into the docs repository’s mcp-server/runtime-surface.json, then run the docs drift check.