@taplid/mcp

Official MCP for the hosted Taplid audit API.

• Docs: https://taplid.com/docs
• Audit page: https://taplid.com/audit

Local MCP (Model Context Protocol) server exposing Taplid audit tools for AI coding agents.

Use Taplid from Claude Desktop, Cursor, or any MCP-aware client. Your Taplid API key stays in the client config, not in the prompt. After updating the config file, restart Claude Desktop and ask it to audit a payload with Taplid.

What it does

Registers three MCP tools: taplid_audit, taplid_get_audit, and taplid_verify_audit.

• taplid_audit runs a hosted Taplid audit. Only response is required; context, prompt, and auditMode are optional. Requires TAPLID_API_KEY.
• taplid_get_audit retrieves a persisted hosted audit by auditId. No API key is required.
• taplid_verify_audit verifies a persisted audit by auditId or verifies a signed attestation token. No API key is required.

Returns ALLOW / REVIEW / BLOCK with a 0-100 trust score and a structured summary.

• No file reading. No command execution. No repo scanning.
• Stdio transport. Local process launched by the MCP client.
• HTTP caller boundary to the existing Taplid API. No engine code is imported.

Install and configure

The package does not need to be globally installed. Claude Desktop or any MCP-aware client can run it through npx, which resolves the package on first invocation. You only need Node.js/npm installed so that the npx command is available. For reliability, pin the exact package version, for example @taplid/[email protected], instead of using latest.

Claude Desktop / Cursor (cross-platform)

Add this block to your MCP client's mcpServers config and npx will resolve the package on first invocation:

{
  "mcpServers": {
    "taplid": {
      "command": "npx",
      "args": ["-y", "@taplid/[email protected]"],
      "env": {
        "TAPLID_API_KEY": "tap_live_...",
        "TAPLID_API_URL": "https://api.taplid.com"
      }
    }
  }
}

Pin the exact MCP package version. Do not use @taplid/mcp or @taplid/mcp@latest, because Claude Desktop / MCP clients may keep using a cached older package even after restart. After Taplid publishes a new MCP version, update this version number manually, then fully quit and reopen the MCP client.

Compatible with MCP-aware clients such as Claude Desktop and Cursor where stdio MCP servers are supported. Specific clients may use their own config formats.

Local development (Windows path)

For local development against a Taplid API running on your machine:

{
  "mcpServers": {
    "taplid-local": {
      "command": "node",
      "args": ["C:\\code\\taplid\\packages\\taplid-mcp\\dist\\server.js"],
      "env": {
        "TAPLID_API_KEY": "tap_live_...",
        "TAPLID_API_URL": "http://127.0.0.1:7000"
      }
    }
  }
}

Environment variables

| Variable | Default | Purpose | |---|---|---| | TAPLID_API_KEY | required for taplid_audit; not required for taplid_get_audit or taplid_verify_audit | Bearer token for the Taplid API. Set this in your MCP client config block. Never passed as a tool input. | | TAPLID_API_URL | falls back to TAPLID_PUBLIC_API_URL, then https://api.taplid.com | Base URL for the Taplid API. | | TAPLID_MCP_TIMEOUT_MS | 60000 | AbortController deadline for each request. Range 1000-600000ms; out-of-range values revert to default. | | TAPLID_MCP_DEBUG | false | When "true", successful responses include a _debug object with {latencyMs, bytesIn, httpStatus}. Bodies and secrets are never included. | | TAPLID_MCP_LOG_LEVEL | info | Pino log level: trace, debug, info, warn, error, fatal, silent. |

Logs go to stderr only. Stdout is reserved for the MCP protocol.

Release notes

v0.5.0

• ITD-442: documents auditMode for the MCP public surface. Use artifact for code reviews and structured artifacts; use standard for short factual or policy checks.

Tool: taplid_audit

MAX_REVIEW_FIELD_CHARS characters (300,000). Oversize input is rejected before the network call.

TAPLID_API_KEY is read from the MCP client env block.

Input fields

| Field | Required | Description | |---|---|---| | context | no | The source material the artifact must be consistent with (diff, spec, code, docs). | | prompt | no | The prompt or task that produced the artifact. | | response | yes | The AI-generated artifact to verify. | | auditMode | no | 'artifact' (default) or 'standard'. Artifact mode is recommended for code reviews, PRs, implementation plans, long answers, and structured outputs. Standard mode is best for factual, policy, refund, pricing, and entitlement issues. |

Worked example

Input (short factual check, standard mode):

{
  "context": "The number is 1.",
  "prompt": "What is the number?",
  "response": "The number is 2.",
  "auditMode": "standard"
}

Expected envelope:

{
  "auditId": "AUD-XXX",
  "auditMode": "standard",
  "decision": "BLOCK",
  "trustScore": 20,
  "summary": "This answer conflicts with the provided context.",
  "issues": [
    {
      "message": "Contradicts the provided context.",
      "reason": "The context states one thing; the response says the opposite."
    }
  ],
  "nextStep": "Do not use this yet. Adjust the answer to match the provided context, then re-run the check.",
  "repairActions": [
    {
      "action": "Rewrite the answer so it aligns with the provided context.",
      "priority": "critical",
      "target": "response"
    }
  ],
  "claims": [
    {
      "text": "The number is 2.",
      "status": "contradicted",
      "evidence": [
        "Response value: 2",
        "Context value: 1"
      ]
    }
  ],
  "diagnosis": {
    "action": "revise_answer",
    "confidence": "high",
    "severity": "error",
    "nextSteps": [
      "Verify the answer is consistent with the provided context before re-running."
    ],
    "explanation": "The answer contradicts the provided context. Revise the answer to align with the source material before re-running the audit."
  },
  "claimStats": {
    "total": 1,
    "supported": 0,
    "unsupported": 0,
    "contradicted": 1,
    "evaluated": 1
  },
  "evidenceCoverage": 1,
  "metadata": {
    "auditDurationMs": 1,
    "claimsDetected": 1,
    "engine": "taplid",
    "version": "1"
  },
  "meta": {
    "policy": {
      "profileId": "balanced",
      "passThreshold": 80,
      "reviewThreshold": 60
    }
  },
  "requestId": "aud_XXX",
  "attestation": {
    "alg": "ES256",
    "kid": "taplid-es256-2026-06",
    "typ": "JWT",
    "issuer": "https://api.taplid.com",
    "issuedAt": "2026-06-12T21:28:52.000Z",
    "inputHash": "91f5884c9a9be6152e6d75534df82dada5965e7905bc80eca95df02970c6f3b1",
    "resultHash": "f95e77eb3224d987fa0baf35b5ee4c4e04029960cdcd6fd16c9171ffad929a7e",
    "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InRhcGxpZC1lczI1Ni0yMDI2LTA2IiwidHlwIjoiSldUIn0..."
  }
}

Tool: taplid_get_audit

Retrieves a persisted hosted audit by auditId.

No API key is required. Treat the audit ID like a share link: anyone with the ID can retrieve the persisted public result. Retrieval is a public lookup. Hosted audit results include an attestation object, which is the cryptographic proof layer.

Input fields

| Field | Required | Description | |---|---|---| | auditId | yes | The audit ID returned by a completed hosted Taplid audit, for example AUD-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. |

Worked example

Input:

{
  "auditId": "AUD-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Expected envelope:

{
  "auditId": "AUD-XXX",
  "auditMode": "standard",
  "decision": "BLOCK",
  "trustScore": 20,
  "summary": "This answer conflicts with the provided context.",
  "issues": [],
  "nextStep": "Review the result before using the answer.",
  "requestId": "aud_XXX",
  "attestation": {
    "alg": "ES256",
    "kid": "taplid-es256-2026-06",
    "typ": "JWT",
    "issuer": "https://api.taplid.com",
    "issuedAt": "2026-06-12T21:28:52.000Z",
    "inputHash": "91f5884c9a9be6152e6d75534df82dada5965e7905bc80eca95df02970c6f3b1",
    "resultHash": "f95e77eb3224d987fa0baf35b5ee4c4e04029960cdcd6fd16c9171ffad929a7e",
    "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InRhcGxpZC1lczI1Ni0yMDI2LTA2IiwidHlwIjoiSldUIn0..."
  }
}

Tool: taplid_verify_audit

Verifies a hosted audit by auditId or verifies a signed attestation token.

No API key is required. Provide exactly one of auditId or token. Audit ID verification can check the persisted public result, signed fields, issuer, signature, and result hash. Token-only verification checks the signature and issuer, but cannot check the result hash without the persisted audit result.

Input fields

| Field | Required | Description | |---|---|---| | auditId | no | The audit ID returned by a completed hosted Taplid audit. | | token | no | The compact ES256 attestation JWT from attestation.token. |

Worked examples

Verify by audit ID:

{
  "auditId": "AUD-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Verify by attestation token:

{
  "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InRhcGxpZC1lczI1Ni0yMDI2LTA2IiwidHlwIjoiSldUIn0..."
}

Signed attestations

Hosted Taplid audit responses include an attestation object. It is an ES256-signed proof that Taplid issued the decision for the audited input and returned public result.

Public verification keys are available at:

https://api.taplid.com/.well-known/jwks.json

The attestation.token can be verified against the JWKS public key. The signed payload includes the auditId, auditMode, decision, trustScore, inputHash, and resultHash.

Response fields

The response may include more fields than listed here. These are the primary fields.

• auditId - unique identifier for this audit run; anyone with this ID can retrieve the persisted public result
• auditMode - the effective mode that actually ran: 'artifact' or 'standard'
• decision - ALLOW, REVIEW, or BLOCK
• trustScore - 0 to 100 public trust signal
• summary - short explanation for the verdict
• issues - concrete problems found in the response
• nextStep - practical guidance for what to do next
• repairActions - prioritized steps to fix the response (priority: critical / high / medium / low)
• claims - individual claims extracted and verified against the context, each with status and evidence
• diagnosis - structured diagnosis (action, confidence, severity, nextSteps, explanation)
• claimStats - counts across the claims array (total / supported / unsupported / contradicted / evaluated)
• evidenceCoverage - 0 to 1 fraction of claims grounded against the supplied context
• metadata - engine metadata (auditDurationMs, claimsDetected, engine, version)
• meta.policy - profileId plus passThreshold / reviewThreshold actually applied to this run
• requestId - server-assigned request id for support and tracing
• attestation - ES256 signed proof that Taplid issued this decision for the audited input and returned public result

repairActions, diagnosis, metadata, meta, requestId, auditId, and attestation are present only when the API returns them.

Error codes

The MCP tools return structured errors with stable codes; no stack traces, no raw upstream bodies.

| Code | When | |---|---| | INVALID_INPUT | Required input is missing or empty, or any other field has an invalid value. | | INPUT_TOO_LARGE | One of context, prompt, response exceeds 128,000 characters. Detected pre-network. | | MISSING_API_KEY | TAPLID_API_KEY is not set for taplid_audit. Not required for taplid_get_audit. | | INVALID_AUDIT_ID | The Taplid API rejected the audit ID format. | | AUDIT_NOT_FOUND | No persisted audit was found for that audit ID. | | UPSTREAM_AUTH_FAILED | The Taplid API returned 401 or 403. | | UPSTREAM_RATE_LIMITED | The Taplid API returned 429. | | UPSTREAM_TIMEOUT | The request did not complete within TAPLID_MCP_TIMEOUT_MS. | | UPSTREAM_UNAVAILABLE | The Taplid API returned 5xx or the host was unreachable. | | UPSTREAM_BAD_RESPONSE | The Taplid API returned a body that was not valid JSON or not the expected shape. | | MCP_INTERNAL | Unexpected internal error. |

Security model

• Three MCP tools: taplid_audit, taplid_get_audit, and taplid_verify_audit. No file I/O, no shell, no process spawning, no inbound network listener.
• Stdio transport launched by the MCP client. The threat model includes hostile tool input and hostile generated artifacts.
• TAPLID_API_KEY is read from the environment only and is never accepted as a tool input.
• taplid_get_audit and taplid_verify_audit do not require TAPLID_API_KEY; the audit ID or signed attestation token is the verification input.
• Signed attestations are verified with the public JWKS at https://api.taplid.com/.well-known/jwks.json; private signing keys are never exposed.
• Logs redact the API key, the Authorization header, and the bodies of context, prompt, response. Stdout is reserved for the MCP protocol.

License

Same license as the parent Taplid workspace.