supercheck-io/supercheck / .agents/skills/mcp-server
supercheck-mcp-server
VerifiedWork on the Supercheck MCP server and its OAuth authorization flow, such as adding or changing an MCP tool, MCP client connections and project scoping, rate and body limits, origin checks, redaction of tool output, or the MCP docs.
Supercheck MCP server
The app exposes a Model Context Protocol endpoint for AI clients: read tools under mcp:read, plus optional incident write tools (mcp:incidents:write) and billable AI SRE tools (mcp:sre). It is off unless MCP_SERVER_ENABLED=true (app/src/lib/mcp/config.ts).
flowchart LR
CLIENT[MCP client] --> ROUTE["/api/mcp route"]
ROUTE --> ORIGIN[Origin check]
ORIGIN --> TOKEN[OAuth access token verified]
TOKEN --> BODY[Bounded body read]
BODY --> LIMIT[Admission keyed on token claims]
LIMIT --> CTX[Call context: org, project, role]
CTX --> TOOL[Tool, gated by scope]
TOOL --> RBAC[assertCanView resource]
RBAC --> QUERY[Org- and project-scoped query]
QUERY --> REDACT[safeText / safeTarget]
Start here
| File | Why |
|---|---|
app/src/app/api/mcp/route.ts | Transport, hasTrustedRequestOrigin, admission, body read |
app/src/lib/mcp/tools.ts | Tool registry (registerMcpTools) and the tool helper every tool goes through |
app/src/lib/mcp/sre-tools.ts | Optional-scope tools; each call re-checks scope and live RBAC |
app/src/lib/mcp/context.ts | resolveMcpCallContext from token claims, assertCanView |
app/src/lib/mcp/call-limits.ts | Per-client and per-user message rates, batch and concurrency caps, readMcpBody |
app/src/lib/mcp/redact.ts, http-policy.ts, auth-plugins.ts | Output redaction, OAuth endpoint deny list, OAuth plugin setup |
User docs: docs/content/docs/mcp/ (tools.mdx, security.mdx, connect.mdx).
Tool rules
- Read tools use the shared annotations (
readOnlyHint: true,destructiveHint: false). A new write or billable tool goes under an optional scope (granted only when both the stored consent and the token carry it), checks its RBAC action per call, reuses the REST route's rate limits and gates, and gets consent copy. - Register every tool through the
tool(...)helper intools.tswith an RBAC resource; it runsassertCanView, maps errors toforbidden/not_found/internal_error, and writes anmcp_tool_callaudit event with ids and timing only (never arguments or results). - Scope every query with the call's
organizationIdandprojectId(thescope()helper). A connection is bound to one project. Tables without an organization column (runs,project_variables) are scoped through the owning project (existsonprojects), and child rows (job tests, requirement links, component monitors) through a project-scoped parent. - Validate arguments with Zod: ids are UUIDs, lists use the shared
pageshape (limitcapped atMAX_LIMIT, cursor is the last id). - Never return scripts, secrets, variable values (
list_variablesreturns variable metadata without values: id, key, type, isSecret, description, updatedAt), headers, auth or request bodies (get_monitoruses an allow-list of scalar settings), notification channels or trigger keys, status page subscribers, investigation prompts, agent state, evidence or cost, or raw response bodies. Pass user-controlled text throughsafeText(bounded, redacted) and monitor targets throughsafeTarget(no credentials or query strings). - Tools returning stored data end their description with the
UNTRUSTEDsuffix (the staticprepare_local_authoringhint is the exception; the write and SRE tools carry it too, viaUNTRUSTEDinconfig.ts): returned text comes from test output or incidents and is prompt-injection input for the client. - Billable AI SRE tools (
mcp:sre: triage, investigate, evidence brief) run the same gates as the REST routes and returnacceptedat once (triage and brief first refuse withconflictwhen a run of that kind is active and not stale, asinvestigate_incidentdoes;startGate); the run continues inafter()and the client pollslist_investigations/get_investigation. Copilot chat is not exposed (streaming). - Return
ok(...)/fail(code, message): structured content plus a JSON text copy; errors are stable codes, not stack traces.
Transport and auth rules
- Request order in
route.ts:POSTchecks the origin (hasTrustedRequestOrigin), thenrequireMcpAuthverifies the token; insidehandle, a Content-Length precheck, admission (admitMcpCall, keyed on the verifiedsub/azpclaims: rate and concurrency, with the one-message charge taken up front), then the bounded body read (readMcpBody,MAX_BODY_BYTESand aMCP_BODY_READ_TIMEOUT_MSdeadline answered with 408; a batch is charged for its extra messages after parsing), then per-call context resolution. Admission cannot move ahead of token verification. Every new code path must stay behind the same checks, and the permit must be released on every exit. - Consent:
mcp:readis always required (rejected at/oauth2/authorizewithinvalid_scope, re-checked in the consent route, which never records a read-less row). The consent row holds the union of scopes approved for (client, project): the consent route wraps approval inwithMergedConsentScopes(connections.ts), since Better Auth's upsert overwrites. Only Disconnect removes scopes. - Auth refusals: a rejected token gets
error="invalid_token"anderror.data.code: invalid_token; an empty batch is-32600; non-POST methods are 405 withAllow: POST.OPTIONS /api/mcpanswers 204 withAllow: POST, OPTIONS(an explicit handler, because Next would otherwise list every exported method). - Dynamic client registration stores
mcp:readonly for a registration that names no scope (clientRegistrationDefaultScopesinauth-plugins.ts); optional scopes must be requested explicitly. - Tokens come from the Better Auth OAuth provider; OAuth HTTP endpoints outside the supported flow are denied (
isOAuthEndpointDenied) and pruned from discovery metadata. resolveMcpCallContextre-checks the user on every call: banned or inactive owners are rejected (isCredentialOwnerActive), not only at connect time.
Verify
- Each tool: happy path, cross-org and cross-project denial, wrong role, malformed id, pagination edge, redaction of secrets and URLs in output.
- Route: forged origin, oversized body, rate and concurrency limits, disabled flag returns no endpoint.
- DB-backed specs (
*.db.spec.ts) run only withnpm run test:db. - Update
docs/content/docs/mcp/tools.mdxwhen the tool surface changes.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |