MCP Server

What is MCP?

MCP (Model Context Protocol) is a standard protocol that lets AI coding tools access external data. Connecting the QA Note MCP server is the handoff path: your agent in Claude Code, Cursor, or Codex receives the issue, works on the fix, and writes progress back to QA Note automatically — so the record keeps itself while developers stay in their own tools.

QA Note delivers rich technical metadata (console logs, network requests, JS errors, performance metrics, React component trees, user actions, element styles, DOM snapshots) to the agent in structured form — a work order it can act on immediately. Note the boundary: agents can record up to fix submitted; transitioning to verified or closed is reserved for humans and report publishing.

One-click install

Pick the MCP client you use and the copy or deep-link action runs immediately. The first connection opens a single browser OAuth consent window.

Auth methods at a glance

The default path is one-click OAuth — no need to paste an Authorization header. Claude Code discovers the QA Note authorization server through the standard MCP discovery endpoint (/.well-known/oauth-protected-resource) and performs Dynamic Client Registration (RFC 7591) → Authorization Code + PKCE S256 → access/refresh token exchange automatically.

Method A. Remote HTTP + one-click OAuth (recommended)

Connect directly to the hosted MCP endpoint at https://qanote.app/api/mcp. No binary install, no API key copy-paste.

Claude Code

One line in your terminal:

claude mcp add --transport http qanote https://qanote.app/api/mcp

After registering, run /mcp in Claude Code — your browser opens automatically, and a single QA Note sign-in + consent completes authentication. The resulting access/refresh tokens are stored safely inside Claude Code and refreshed transparently from then on.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "qanote": {
      "url": "https://qanote.app/api/mcp"
    }
  }
}

No headers — Cursor launches the OAuth browser window on first tool call.

Codex (OpenAI)

Same entry under mcpServers in your Codex CLI config:

{
  "mcpServers": {
    "qanote": {
      "url": "https://qanote.app/api/mcp"
    }
  }
}

OAuth flow under the hood

1. The client calls https://qanote.app/api/mcp → 401 Unauthorized with WWW-Authenticate: Bearer resource_metadata=...
2. The client reads /.well-known/oauth-protected-resource (RFC 9728) → /.well-known/oauth-authorization-server (RFC 8414) to get the authorization server metadata
3. Dynamic Client Registration (RFC 7591) issues a client_id automatically (no user action needed)
4. Authorization Code + PKCE S256 flow — browser sign-in + MCP consent
5. /api/oauth/token returns an access token (scopes mcp + offline_access, bound with aud=https://qanote.app/api/mcp — RFC 8707) and a refresh token
6. Subsequent requests keep the same refresh token and silently renew only the access token

The "MCP Prompt" button on each issue page copies a prompt that embeds the issue permalink so the LLM can pull the full context with a single resolve_by_url call.

Method B. Local binary (stdio · npx)

Use this when your corporate network blocks HTTP MCP, or when you want credentials cached locally for offline/SSH environments. The auth itself is the same OAuth browser flow.

Claude Code

claude mcp add qanote -- npx -y @qanote/mcp-server

Cursor / Codex

{
  "mcpServers": {
    "qanote": {
      "command": "npx",
      "args": ["-y", "@qanote/mcp-server"]
    }
  }
}

Authentication flow

1. On first launch, if no stored credential exists, the browser opens automatically
2. Log in with your QA Note account (if already signed in, only the consent step remains)
3. The resulting token is saved to ~/.qanote/credentials.json with chmod 600
4. Subsequent runs reuse the stored token automatically and silently renew only the access token

To reset credentials:

rm ~/.qanote/credentials.json

Method C. API Key (CI · headless · fallback)

Use this only in environments where a browser cannot be opened (CI/CD, containers, remote servers) or with MCP clients that do not support OAuth.

1. QA Note Dashboard → Organization Settings → API Keys
2. "New API Key" → enter a name (e.g., QA Note production server), pick an expiry and permissions → "Create"
3. Copy the displayed key (qn_...) immediately to a safe location (shown only once)

For server-side data import, keep the default projects:read + issues:read permissions. Add issues:write only when the automation needs to update issue status or create comments. To keep production and developer credentials separate, use an API Key for the server and a separate OAuth connection for interactive tools like Claude Code.

API Key with Remote HTTP

claude mcp add --transport http qanote https://qanote.app/api/mcp \
  --header "Authorization: Bearer qn_YOUR_KEY"

Cursor / Codex JSON:

{
  "mcpServers": {
    "qanote": {
      "url": "https://qanote.app/api/mcp",
      "headers": { "Authorization": "Bearer qn_YOUR_KEY" }
    }
  }
}

API Key with stdio binary

{
  "mcpServers": {
    "qanote": {
      "command": "npx",
      "args": ["-y", "@qanote/mcp-server"],
      "env": {
        "QANOTE_API_KEY": "qn_YOUR_KEY"
      }
    }
  }
}

Environment variables (stdio binary)

Remote HTTP does not need environment variables since the client specifies the url directly.

Available tools

Query tools

Write tools

Project list lookup

list_projects is the first discovery tool an LLM should use when the user has not provided an issue URL.

When to use it

• "Show me the QA Note project list"
• "Show only projects in the studiobaton organization"
• "Find critical issues in the qa-note project"
• "Show the next issue queue from a project I can access"

If the user already pasted an issue permalink, call resolve_by_url first instead.

Input

Response fields

list_projects returns a JSON array.

Example:

[
  {
    "id": "018f2f4b-...",
    "name": "QA Note",
    "slug": "qa-note",
    "description": null,
    "createdAt": "2026-04-21T08:13:44.000Z",
    "organizationId": "018f2d10-...",
    "organizationSlug": "studiobaton",
    "organizationName": "Studio Baton"
  }
]

Permissions and multi-org behavior

• OAuth connections are user-scoped. If the user belongs to multiple organizations, projects from every accessible active organization are returned.
• API Key connections return projects only from the organization that issued the key.
• Different organizations can have projects with the same slug. The LLM should resolve projects by organizationSlug + slug or by id, not by slug alone.
• If the organization is ambiguous, the LLM should ask the user which organization to use instead of picking the first result.

LLM usage scenarios

User: "Show me the QA Note project list"
LLM: Call list_projects({}) → summarize organization name/slug and project name/slug

User: "Show open issues in the QA Note project under studiobaton"
LLM:
1. list_projects({ "organization_slug": "studiobaton" })
2. Select the project whose slug or name matches QA Note
3. search_issues({ "project_id": "<id>", "status": "open" })

User: "Find critical issues in the qa-note project"
LLM:
1. list_projects({})
2. If multiple projects have slug qa-note, ask "Which organization: studiobaton/qa-note or client-a/qa-note?"
3. Call search_issues with the confirmed project_id

User: "Show my next work queue for qa-note"
LLM:
1. list_projects({})
2. Resolve the project by organizationSlug + slug
3. list_issue_queue({ "project_id": "<id>", "status": "open", "sort": "board_order" })

Recommended workflows

Just make natural-language requests to your AI coding tool:

# Search issues
"Find critical issues in QA Note"

# Debugging context
"Show me the console errors and network logs for issue #42"

# Reproduce user behavior
"Tell me what the user did in issue #15"

# Update an issue
"Move issue #42 to resolved and leave a comment about the fix"

Optimal debugging sequence:

1. Copy a permalink-embedded prompt from the "MCP Prompt" button on any issue page → one resolve_by_url call
2. Dig deeper with get_tech_context · get_console_logs · get_network_logs
3. After resolution, call update_issue to change status and add_comment to record cause/fix

Verify setup

After setup, try asking your AI tool:

Show me the project list from QA Note

If the project list appears, setup is complete.

Troubleshooting

OAuth browser window does not open (Remote HTTP)

• In firewall/popup-blocker environments, copy the authorize URL printed by Claude Code into a browser manually to finish sign-in + consent. The token is then saved automatically.
• If a corporate proxy blocks .well-known/oauth-* discovery, switch to Method B (stdio binary) or use Method C (API Key).

"Unauthorized" error

• OAuth path: the stored token has expired or was revoked. Restart the MCP server to re-trigger browser login. For the stdio binary, delete ~/.qanote/credentials.json.
• API Key path: verify the key starts with qn_ and has not been revoked. To access a different organization's resources, issue a new key in that organization.

invalid_grant — Refresh token reuse detected

This can appear during migration from the older OAuth server behavior that rotated MCP refresh tokens. The current server keeps MCP refresh tokens persistent, so repeated refreshes with the same token should work. If the error persists, delete the client's stored OAuth token once and reconnect.

MCP server won't connect (stdio binary)

• Run npx -y @qanote/mcp-server directly in your terminal to confirm it boots
• Requires Node.js 20+
• Check that QANOTE_URL / QANOTE_API_KEY are set correctly in the MCP config's env block

Reset token/session

# stdio binary
rm ~/.qanote/credentials.json

# Remote HTTP (Claude Code)
claude mcp remove qanote
claude mcp add --transport http qanote https://qanote.app/api/mcp

SSH · Docker — no browser available

→ Use Method C (API Key). Injecting the key via environment variable or --header is the safest option for CI/CD pipelines.