Skip to main content

npc-verify-mcp — "Verified by NPC" MCP server

Ask "is this real?" inside any MCP-capable assistant. This MCP server puts NPC Labs verification inside Claude Desktop, Claude Code, and friends: check a product, credential, claim, or AI agent against NPC Labs verification records. Every tool is a thin call to the NPC Verification API v1 — no verification logic lives here — and every API response is Ed25519 signature-verified client-side before it reaches the caller. Fail-closed everywhere: unknown subjects return "unknown", never a guess.

  • Zero dependencies. Pure Python standard library. The MCP JSON-RPC transport is implemented directly over stdio; the signing primitives are the API reference implementation (vendored byte-identical copies ship inside the package, so a PyPI install needs no repo checkout).
  • Public API by default. Talks to the NPC Verification API at https://api.npclabs.xyz by default (override with NPC_VERIFY_API_URL, e.g. http://127.0.0.1:8787 for a local API). No key setup is required: a public read-only verifier key is bundled, the same posture as the Chrome extension. Set NPC_VERIFY_API_KEY to use your own key.

Layout

plugins/mcp/
  pyproject.toml
  README.md            # this file
  docs/TOOLS.md        # tool reference
  npc_verify_mcp/
    __init__.py
    __main__.py        # npc-verify-mcp entry point
    server.py          # MCP JSON-RPC 2.0 transport over stdio
    tools.py           # the five tools (schemas + thin handlers)
    api_client.py      # API v1 HTTP client + signature verification
  tests/
    test_tools.py      # per-tool tests against seeded fixtures
    test_signature.py  # signature verification incl. tamper rejection
    test_contracts.py  # Proofline-style contract suite
    test_transport.py  # stdio JSON-RPC round trips

Quick start

# 1. Install the MCP server
pip install npc-verify-mcp        # or: uvx npc-verify-mcp
# (from a repo checkout instead: pip install -e . in plugins/mcp)

# 2. Run it. No configuration is needed: it talks to the public API at
#    https://api.npclabs.xyz with a bundled read-only verifier key.
npc-verify-mcp

# Optional: use your own key, or point at a local API for development
export NPC_VERIFY_API_KEY="npc_..."                  # your verifier key
export NPC_VERIFY_API_URL="http://127.0.0.1:8787"    # local API override

Developers: the tests run against a locally seeded API fixture. python3 -m unittest discover -s tests from plugins/mcp/.

Claude Desktop config

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "npc-verify": {
      "command": "uvx",
      "args": ["npc-verify-mcp"]
    }
  }
}

No environment is required: the server defaults to the public API with a bundled read-only verifier key. To use your own key or a local API, add an env block with NPC_VERIFY_API_KEY and/or NPC_VERIFY_API_URL. If the API is unreachable, the tools report an error instead of guessing.

The five tools

Tool Answers Backend
verify_claim "Did this really happen / is this claim true?" POST /v1/claims/verify
verify_credential "Is this certificate real?" GET /v1/credentials/{id}
verify_product "Is this product authentic?" GET /v1/products/{tag_id}
verify_agent "Is this agent verified?" GET /v1/agents/{agent_id}/attestation
explain_verification "What does Verified by NPC mean?" static public-safe explainer

Tool descriptions carry the trigger phrasing ("is this real?", "verify this", "is this authentic?") so the agent-recommends channel can surface them mid-conversation. Full reference: docs/TOOLS.md.

Security model

  • Verify, don't trust. Every API response body is canonicalized and Ed25519-signed by the API. The client checks the X-NPC-Signature header against the API's published keys (GET /v1/keys, current + rotation history) on every call. A failed check is fail-closed: the caller gets an error, never the data.
  • Fail-closed errors. Unknown subject → "unknown". Missing or bad arguments → error, not a guess. Unreachable API → error naming the fix. Tampered response → error.
  • No PII beyond public. Tool outputs are the API's already-sanitized responses, passed through unchanged.
  • No mark usage. The "Verified by NPC" mark ships only after counsel clearance (program gate §8). The capability builds now.

Environment

Variable Default Purpose
NPC_VERIFY_API_URL https://api.npclabs.xyz API base URL
NPC_VERIFY_API_KEY bundled public read-only verifier key Verifier API key override
NPC_VERIFY_API_PATH auto-detected Override: dir holding the api/ tree

What this does NOT do

  • No attestation issuance (read-first; POST /v1/attestations is not exposed).
  • No mark usage in the server itself.
  • No methodology exposure: explain_verification teaches the why only.

Metadata

Release files for npc-verify-mcp 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for npc-verify-mcp 1.0.1
File Size Uploaded Provenance Actions
npc_verify_mcp-1.0.1.tar.gz 20.5 kB Without provenance Details for npc_verify_mcp-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for npc-verify-mcp 1.0.1
File Interpreter ABI Platform Actions
npc_verify_mcp-1.0.1-py3-none-any.whl Python 3 none any Details for npc_verify_mcp-1.0.1-py3-none-any.whl

Total release size: 37.5 kB

Release files / npc_verify_mcp-1.0.1.tar.gz

Download URL npc_verify_mcp-1.0.1.tar.gz
Size 20.5 kB
Tags Source
SHA-256 checksum
How to use checksums
2fcada27cb36870c6f6a7426cf999b19ce0adfb0e478e049e0276fe16271d118
BLAKE2b-256 checksum
How to use checksums
6ec51a9566f8017e25388e4560cf15060d6ef873f6aeeade9aad1f217ca921cc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / npc_verify_mcp-1.0.1-py3-none-any.whl

Download URL npc_verify_mcp-1.0.1-py3-none-any.whl
Size 17.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d8159ff9634a0640abe087c59c64a12c4ceda4ace40b75bcd60bd1cee6144a4c
BLAKE2b-256 checksum
How to use checksums
e9475f94f398eddc8084dfcfe7b698920edee52c3dcb70c0419daac6f0c7e22a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for npc-verify-mcp 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page