MCP Clients

Gricea exposes a Streamable HTTP MCP endpoint at:

/api/mcp

Use MCP when a researcher wants an external assistant to read Gricea context or search public study metadata from a trusted client such as Codex or Claude.

Current production scope:

• Authenticated MCP access keys created from Settings (API Keys & Datasets)
• Hashed key storage with revocation
• Per-token rate limiting
• Read/search tools for public or organization-authorized Gricea context
• Draft-only study creation through draft_study, gated by the researcher:draft permission
• Draft-only study refinement through refine_study, gated by the researcher:draft permission
• Consent-gated conversation donation through preview_donation_redaction and donate_conversation, gated by the donor:upload permission

Not yet production scope:

• Publishing studies from MCP

Publishing remains a roadmap item and should only ship after it reuses the same preview, validation, and researcher review layers as the web UI.

1. Open Settings (API Keys & Datasets) from the researcher dashboard.
2. Find MCP access keys.
3. Enter a client-specific name such as "Codex local" or "Claude desktop".
4. Choose permissions. Similar-study search is always included; draft study creation/refinement and conversation donation are opt-in.
5. Create the key and copy it immediately. Gricea only shows the raw secret once.
6. Store the secret in an environment variable on the machine running the MCP client:

export GRICEA_MCP_API_KEY="grk_..."

Use separate keys per client or machine. Revoke a key from the same settings page if a device is lost, a teammate leaves, or a key is accidentally shared.

Codex reads MCP server configuration from its config file. Add a Streamable HTTP server entry that points at your Gricea deployment. For current Codex MCP guidance, keep https://developers.openai.com/codex/mcp open alongside this page.

1. Create a Gricea MCP key with the scopes your Codex workflow needs.
2. Export the key in the shell that launches Codex:

export GRICEA_MCP_API_KEY="grk_..."

1. Add this server entry to your Codex config:

[mcp_servers.gricea]
url = "https://your-gricea-host.example.com/api/mcp"
bearer_token_env_var = "GRICEA_MCP_API_KEY"
tool_timeout_sec = 90

For local development, use the local server URL:

[mcp_servers.gricea]
url = "http://localhost:3000/api/mcp"
bearer_token_env_var = "GRICEA_MCP_API_KEY"
tool_timeout_sec = 90

1. Restart Codex. In the Codex TUI, use /mcp to confirm the gricea server is connected, then ask Codex to list available Gricea tools.

Expected tools depend on the key scopes:

• researcher:read: search_similar_studies
• researcher:draft: draft_study, refine_study
• donor:upload: preview_donation_redaction, donate_conversation

If the key is missing, revoked, or rate-limited, Gricea returns an MCP error instead of falling back to browser cookies.

ChatGPT connects to MCP servers through Apps/Connectors. Use this path when you want a researcher to talk to Gricea from ChatGPT and create or refine a draft study that is later reviewed in the Gricea builder.

1. Make the Gricea MCP endpoint reachable over HTTPS. For deployed Gricea, use:

https://your-gricea-host.example.com/api/mcp

For local development, use a secure tunnel such as the OpenAI Secure MCP Tunnel, ngrok, or Cloudflare Tunnel, then point ChatGPT at the tunneled /api/mcp URL. 2. In ChatGPT, enable developer mode if your workspace allows it, then open Settings -> Apps & Connectors -> Create. 3. Set the connector URL to your public Gricea MCP endpoint and use a description such as:

Use Gricea to search similar studies and create draft conversational-AI research studies. Drafts must be opened in Gricea, previewed, validated, and published by a researcher.

1. Authenticate the connector with an MCP key that has the narrowest needed scopes:

• Discovery only: researcher:read
• Study drafting: researcher:read + researcher:draft
• Donation workflows: donor:upload

1. After ChatGPT shows the tool list, start with a low-risk prompt:

Use Gricea to search for studies about AI consonance and trust. Do not create or modify a study yet.

1. For study creation, use an explicit draft-only prompt:

Use Gricea to create a draft study about AI consonance and perceived trust. Keep it simple: consent, demographics, two task conditions, and a final trust survey. After creating the draft, give me the builder link and a checklist for what I need to preview before publishing.

Gricea MCP tools can create and refine drafts, but they cannot publish studies. The human researcher still owns preview, validation, API-key setup, participant invite creation, and publish decisions.

Use the same endpoint and bearer token. The exact config file shape depends on the client and version, but the required values are:

• Transport: Streamable HTTP
• URL: https://your-gricea-host.example.com/api/mcp
• Authorization: Bearer $GRICEA_MCP_API_KEY

For clients that accept JSON MCP server definitions, use this shape as the source of truth and adapt field names to the client:

{
  "mcpServers": {
    "gricea": {
      "type": "http",
      "url": "https://your-gricea-host.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${GRICEA_MCP_API_KEY}"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "gricea-local": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer ${GRICEA_MCP_API_KEY}"
      }
    }
  }
}

If a client only supports command-based MCP servers, use a local bridge/proxy that reads GRICEA_MCP_API_KEY from the environment and forwards Streamable HTTP requests to Gricea. Do not paste MCP secrets into study prompts, task instructions, screenshots, or shared documents.

The safest researcher workflow is draft -> inspect -> preview -> publish. MCP covers only the draft/refine parts.

1. Ask the agent to search for similar studies first:

Search Gricea for prior studies about consonance, trust, and AI assistants. Summarize reusable design patterns before drafting anything.

1. Ask the agent to create a draft:

Create a draft study named "Simple Study Consonance" with a consent survey, a demographics survey, two conversational-AI task conditions, and a final trust survey. Do not publish it. Return the Gricea builder link.

1. Open the returned builderPath in Gricea. Check every survey question, task prompt, provider/model setting, randomization rule, and completion path.
2. Use builder preview to walk through the researcher path. Fix or refine the draft from either Gricea or the MCP client.
3. Publish only from Gricea after preview, validation, API-key checks, and participant-facing copy are acceptable.

The draft_study and refine_study tool responses return a builderPath, for example:

{
  "draft": {
    "studyId": "507f1f77bcf86cd799439011",
    "name": "Simple Study Consonance",
    "status": "draft",
    "version": 1,
    "modelConfig": {
      "provider": "openai",
      "model": "gpt-4o"
    },
    "builderPath": "/admin/studies/507f1f77bcf86cd799439011/builder"
  }
}

Provider note: draft_study and refine_study use Gricea's server-side AI provider configuration. If you pass provider or a provider-specific model, Gricea resolves that provider from organization settings or environment fallback. If you do not specify a provider, Gricea keeps the existing OpenAI-first behavior and then falls back to another configured provider such as Google Gemini.

Before debugging a client-specific config, verify the Gricea endpoint directly from the same machine that will run the MCP client.

Check metadata:

curl -sS https://your-gricea-host.example.com/api/mcp

Expected response shape:

{
  "name": "gricea",
  "transport": "streamable-http",
  "tools": ["search_similar_studies", "draft_study", "refine_study", "preview_donation_redaction", "donate_conversation"]
}

Check authenticated tool discovery:

curl -sS https://your-gricea-host.example.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GRICEA_MCP_API_KEY" \
  -d '{"jsonrpc":"2.0","id":"tools","method":"tools/list"}'

Check a read-only tool call:

curl -sS https://your-gricea-host.example.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GRICEA_MCP_API_KEY" \
  -d '{"jsonrpc":"2.0","id":"search","method":"tools/call","params":{"name":"search_similar_studies","arguments":{"query":"voice agents trust","limit":3}}}'

Check draft study creation with a researcher:draft key:

curl -sS https://your-gricea-host.example.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GRICEA_MCP_API_KEY" \
  -d '{"jsonrpc":"2.0","id":"draft","method":"tools/call","params":{"name":"draft_study","arguments":{"name":"Simple Study Consonance","description":"Create a simple draft study comparing consonant and dissonant AI responses on perceived trust. Include consent, demographics, two task conditions, and a final trust survey. Keep it draft-only and return a builder link."}}}'

Check draft study creation with a non-default provider:

curl -sS https://your-gricea-host.example.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GRICEA_MCP_API_KEY" \
  -d '{"jsonrpc":"2.0","id":"draft-gemini","method":"tools/call","params":{"name":"draft_study","arguments":{"provider":"google-gemini","model":"gemini-3.5-flash","name":"Simple Study Consonance","description":"Create a simple draft study comparing consonant and dissonant AI responses on perceived trust. Include consent, demographics, two task conditions, and a final trust survey. Keep it draft-only and return a builder link."}}}'

Common failures:

• 401: the key is missing, malformed, revoked, or copied with extra whitespace.
• 403: the key is valid but lacks the scope needed by that tool.
• 429: the key hit the per-token MCP rate limit. Wait for the retry window or use separate keys per automation.
• Empty tool list: the key has no valid scopes. Recreate the key with the intended permissions.
• Connection refused locally: the Gricea dev server is not running on the URL configured in the client.