MCP API Documentation

How to connect to the MCP API via OAuth (Claude.ai and others) or an API token (Bearer).

Treat your API token like a password and do not share it.

MCP API – Connecting to Promptdoo

This page explains how to connect to the MCP API (Model Context Protocol) at /api/v1/mcp, either automatically via OAuth (Claude.ai, Claude Desktop, and other MCP-aware clients) or manually via an API token used as a Bearer token (custom scripts, Cursor, agent frameworks).

Overview

The MCP API is available at /api/v1/mcp.
Two ways to authenticate:

1. OAuth — the client (e.g. Claude.ai's connector settings) registers and authorizes itself automatically. No token to copy/paste. Use this if your client supports it.
2. API token (Bearer) — you create a token manually and pass it in the Authorization header. Use this for scripts, Cursor, or any client without OAuth support.

Either way, treat the resulting credential like a password: keep it secret.

1) Connect via OAuth (Claude.ai, Claude Desktop, and other MCP clients)

If your client supports the MCP Authorization spec (OAuth 2.1 with Dynamic Client Registration and PKCE) — this includes Claude.ai's Connectors settings — just add the MCP URL directly:

https://promptdoo.com/api/v1/mcp

What happens next, automatically:

1. The client discovers the OAuth endpoints via /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.
2. It registers itself as an OAuth client (no manual client ID needed).
3. You're redirected to Promptdoo to log in (if needed) and approve the connection on a consent screen.
4. The client receives a short-lived access token plus a refresh token and keeps itself connected — no token copy/pasting, no manual renewal.

Managing the connection: every app connected this way — including via OAuth — shows up under Connected apps in your profile (/user/profile/edit, "Connected apps" tab). Revoke it there at any time; this immediately invalidates both the access token and any refresh token, so the client cannot silently reconnect.

Advanced / for implementers of other MCP clients, the relevant endpoints are:

Authorization server metadata: GET /.well-known/oauth-authorization-server
Protected resource metadata: GET /.well-known/oauth-protected-resource
Dynamic client registration: POST /oauth/register
Authorization (consent): GET/POST /oauth/authorize
Token exchange / refresh: POST /oauth/token
Revocation: POST /oauth/revoke

Notes:

Only public clients are supported (no client secret) — every authorization request must use PKCE (code_challenge_method=S256).
Access tokens expire after 1 hour; refresh tokens are valid for 180 days and rotate on every use.
If you don't want or can't do the OAuth flow, use a manual API token instead — see below.

2) Getting useful results out of `prompt_optimize`

The MCP server currently exposes one tool: prompt_optimize. It's a prompt-engineering tool, not a content generator — it takes a prompt and returns an improved prompt, it does not answer that prompt. Through a chat-style MCP client like Claude.ai, that's easy to miss at first: ask it to "summarize cats" via the tool and you'll get back a longer, more structured prompt about summarizing cats — not a summary.

Ask for both steps in one message

If you actually want the answer, not just the improved prompt, ask the client to do both in one go, e.g.:

Optimize this prompt with the MCP tool and then answer it directly:
"Write a short summary about cats"

The client (e.g. Claude) will call prompt_optimize, then use the result as its own working prompt to produce the actual answer — no separate follow-up message needed.

Ask for the extra parameters explicitly

An MCP client decides on its own which arguments to send to the tool — left to itself, it usually only sends prompt. The tool supports more (see the full schema in section 7, Examples):

use_case: automatic | coding | reasoning | creative
options.tone, options.target_audience, options.verbosity (short/medium/long), options.output_format, options.constraints
options.programming_language, options.stack (useful together with use_case: coding)

Mention these explicitly in your request and the client will pass them through, e.g.:

Optimize this prompt for a coding assistant, output format Markdown,
verbosity short: "..."

When it's actually worth it

For a one-off, simple question asked directly in a chat, optimizing first adds little — the model would cover the relevant angles anyway, and the optimized prompt can end up longer than the answer you wanted. The tool pays off when:

The prompt gets reused — in automations, other tools (Cursor, your own scripts via the Bearer-token API), or a system prompt that runs many times and needs a consistent result shape.
You're targeting a different model/tool than the one doing the optimizing — the structure helps most where there's no second pass to fix ambiguity, e.g. feeding the optimized prompt into a different LLM, API, or pipeline that can't ask clarifying questions.
Consistency matters more than convenience — e.g. a team or product standardizing how a certain type of prompt gets written.

3) Connect via API token (Bearer)

For scripts, Cursor, agent frameworks, or any client that doesn't do OAuth:

1. Sign in to your account.
2. Open API Settings (e.g. /user/api-settings).
3. Choose a token name (e.g. “My Agent App”).
4. Optional:

Note: what you use the token for.
Default LLM: used if your client does not provide a model_id.

5. Click “Create new token”.

Important:

The token is shown only once right after creation.
Store it immediately in a safe place (e.g. password manager).

4) Store the token securely (best practices)

Do not store the token in public repositories or frontend code.
Use environment variables (e.g. .env), secret managers, or a password manager.
If you suspect the token was compromised:
revoke it in the UI (works the same for OAuth-issued and manually created tokens — both show up under Connected apps / API Tokens)
create a new token

5) Authentication (Bearer token)

For every request to the MCP API, set the header:

Authorization: Bearer YOUR_TOKEN_HERE

This applies whether the token came from the manual API-token flow or was issued via OAuth — the MCP endpoint itself doesn't care which.

Optional (only for tokens created via the browser-extension pairing flow, not for OAuth or manually created tokens):

X-Instance-Id: YOUR_INSTANCE_ID

6) MCP endpoint

URL: POST https://promptdoo.com/api/v1/mcp
Content-Type: application/json

The MCP API uses JSON-RPC. That means you send a JSON object with jsonrpc, id, method and optionally params.

7) Examples

7.1 Initialize

curl -sS https://promptdoo.com/api/v1/mcp \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize"
  }'

7.2 List tools

curl -sS https://promptdoo.com/api/v1/mcp \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

7.3 Call a tool: `prompt_optimize`

Minimal:

curl -sS https://promptdoo.com/api/v1/mcp \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "prompt_optimize",
      "arguments": {
        "prompt": "Write a short email asking for a meeting next week"
      }
    }
  }'

With an explicit model (overrides the token default) and the extra tuning parameters from section 2 ("Getting useful results out of prompt_optimize"):

curl -sS https://promptdoo.com/api/v1/mcp \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "prompt_optimize",
      "arguments": {
        "prompt": "Improve this prompt for a coding assistant...",
        "model_id": 12,
        "json_mode": false,
        "use_case": "coding",
        "options": {
          "tone": "professional",
          "verbosity": "short"
        }
      }
    }
  }'

8) Credits & usage

MCP calls consume credits depending on the selected model — this applies the same way whether the call came in via an OAuth-issued token or a manually created one.
In the UI under API Tokens, you can view usage (credits) per token.

9) Integration in agent apps

You can integrate the MCP API into agent apps by sending requests to /api/v1/mcp and using a Bearer token — either issued via OAuth or created manually, see above.

Important:

Treat the token like a password (do not commit it to a repo).
Prefer environment variables / secret managers for manually created tokens.
For local tools or desktop apps, consider using one token/connection per app.

9.1 Claude.ai / Claude Desktop (Connectors)

Use the OAuth flow described in section 1 — add https://promptdoo.com/api/v1/mcp as a connector URL, log in, and approve the consent screen. No manual token needed. Manage or revoke the connection later under Connected apps in your profile.

See section 2 ("Getting useful results out of prompt_optimize") for how to actually get an answer out of the tool, not just an improved prompt.

9.2 Cursor

To configure Cursor to use your MCP API as a tool backend, you need:

the base URL (e.g. https://promptdoo.com)
an API token from /user/api-settings (see section 3 — Cursor does not currently do the OAuth flow)

Depending on your Cursor version/setup, configuration may be done via MCP settings or a “custom tool/server”. The key requirement is that Cursor sends JSON-RPC requests to POST /api/v1/mcp and sets the header:

Authorization: Bearer YOUR_TOKEN_HERE

9.3 OpenAI Agents SDK

If you use the OpenAI Agents SDK, you can expose your MCP tools as a “remote tool” by making an HTTP request to your MCP API when the agent triggers a tool call.

Minimal flow:

1. The agent decides to use a tool (e.g. prompt_optimize)
2. Your code calls POST /api/v1/mcp via JSON-RPC (tools/call)
3. You return the result back to the agent

Your API token should live in a secret source (environment variable) and must not appear in logs or error messages.

10) Common errors

401 Unauthorized

Causes:

Authorization header is missing
token is invalid or expired
token was revoked

For OAuth clients, a 401 on /api/v1/mcp includes a WWW-Authenticate: Bearer resource_metadata="..." header pointing back at the discovery document — well-behaved MCP clients use this to (re-)authenticate automatically.

OAuth registration/authorization errors