Enables AI agents to query cryptographically verified attributes and zero-knowledge proofs from confidential documents without exposing plaintext.
Also known as lemmaoracle/lemma, @lemmaoracle/mcp
- Stars
- 1
- Tools
- 5
- Downloads, 30 days
- 230
- Latest version
- 0.0.17
- Last commit
- Nov 15, 2026
- License
- —
What is Lemma MCP?
Lemma enables AI agents to query cryptographically verified attributes and zero-knowledge proofs from confidential documents without exposing plaintext. It exposes 5 tools, such as lemma_query_verified_attributes, lemma_get_schema, lemma_get_circuit.
Summary generated from the project's README
About Lemma MCP server
Querying cryptographically verified attributes from confidential documents without exposing plaintext is what this server enables for AI agents. It connects models to the Lemma provenance layer, allowing them to access zero-knowledge proofs, selective disclosure, and tamper-evident provenance. This setup ensures that sensitive information remains private while providing verifiable data to the agent.
Developers can integrate this via Claude Desktop using npx and a LEMMA_API_KEY, or through a hosted Smithery gateway. The current MVP provides five read-only tools including lemma_query_verified_attributes, lemma_get_schema, lemma_get_circuit, lemma_get_generator, and lemma_get_proof_status. While write tools like lemma_register_document and lemma_submit_proof are planned for a future phase, the current version focuses on retrieving schemas, circuits, and verification statuses.
This implementation uses the official Model Context Protocol SDK and communicates with a Lemma API deployed on Cloudflare Workers. It is designed to transmit only commitments, hashes, and proofs to maintain privacy, ensuring the underlying plaintext documents are never exposed to the API or the agent.
What you can do with it
- 1Verify document attributes privatelyAn AI agent can find documents that meet specific criteria by querying verified attributes without seeing the actual document content.
- 2Inspect zero-knowledge proof structuresDevelopers can retrieve specific ZK proof circuits to understand the constraints and verifiers being used.
- 3Check proof verification statusAn agent can confirm whether a specific proof has been successfully verified using its unique identification number.
- 4Retrieve data schemasAn AI can pull the attribute structure of a Lemma schema to understand how data is organized.
Written from the project's README. Every use case is checked against a quote from it.
How to install Lemma MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Lemma MCP in Claude Code
$ claude mcp add --env 'LEMMA_API_KEY=<YOUR_LEMMA_API_KEY>' mcp -- npx -y @lemmaoracle/mcpInstall Lemma MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@lemmaoracle/mcp"
],
"env": {
"LEMMA_API_KEY": "<YOUR_LEMMA_API_KEY>"
}
}
}
}Install Lemma MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@lemmaoracle/mcp"
],
"env": {
"LEMMA_API_KEY": "<YOUR_LEMMA_API_KEY>"
}
}
}
}Install Lemma MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@lemmaoracle/mcp"],"env":{"LEMMA_API_KEY":"<YOUR_LEMMA_API_KEY>"}}'Install Lemma MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@lemmaoracle/mcp"
],
"env": {
"LEMMA_API_KEY": "<YOUR_LEMMA_API_KEY>"
}
}
}
}Install Lemma MCP in Codex
$ codex mcp add mcp --env 'LEMMA_API_KEY=<YOUR_LEMMA_API_KEY>' -- npx -y @lemmaoracle/mcpInstall Lemma MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@lemmaoracle/mcp"] [mcp_servers.mcp.env] LEMMA_API_KEY = "<YOUR_LEMMA_API_KEY>"
Install Lemma MCP in Gemini CLI
$ gemini mcp add -s user -e 'LEMMA_API_KEY=<YOUR_LEMMA_API_KEY>' mcp npx -- -y @lemmaoracle/mcpInstall Lemma MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@lemmaoracle/mcp"
],
"env": {
"LEMMA_API_KEY": "<YOUR_LEMMA_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @lemmaoracle/mcp 0.0.17 in an isolated container with no network and no keys. It answered and listed 5 tools.
Lemma MCP tools 5
Read from the server with tools/listlemma_query_verified_attributesRead-onlyQuery cryptographically verified attributes from Lemma. Use this as the primary tool for finding documents whose attributes match given conditions (e.g., "subject's birthYear lt 2008"). Returns { results: Array<{ docHash, schema, issuerId, subjectId, attributes, isVerified, proof?: { status, circuitId, chainId }, disclosure? }>, hasMore }. The MCP layer enriches each item with an `isVerified` flag derived from `proof.status` (true when status is 'verified' or 'onchain-verified'). Use lemma_get_proof_status to monitor a specific proof; use lemma_get_schema to interpret the keys returned in `attributes`.
lemma_get_schemaRead-onlyRetrieve a Lemma schema by its ID via GET /v1/schemas/{id}. A schema declares how documents of a given type are interpreted and normalized. Returns SchemaMeta { id, description? } with additionalProperties open — implementations commonly include a `normalize` artifact (WASM that maps raw documents to canonical form) and its content hash. Use this when you need to interpret attribute keys returned by lemma_query_verified_attributes.
lemma_get_circuitRead-onlyRetrieve a zero-knowledge proof circuit by its circuitId via GET /v1/circuits/{circuitId}. A circuit defines the constraints that proofs must satisfy and binds to a single schema. Returns CircuitMeta { circuitId, schema, description?, inputs?, verifier?: { type: 'onchain'|'offchain', address?, chainId? }, artifact?: { location: { type: 'ipfs'|'https', wasm, zkey } } }. Use this before lemma_submit_proof to confirm the circuit's schema, public inputs, and verifier configuration. Circuits are immutable; new variants get new circuitIds.
lemma_get_generatorRead-onlyRetrieve a Lemma document generator by generatorId via GET /v1/doc-generators/{generatorId}. A generator describes how a class of source documents is produced (e.g., what fields a 'KYC-v2' issuer must populate). Returns GeneratorMeta { generatorId, schema, description?, language?, source?: { type: 'url', uri }, inputsSpec?, outputsSpec? }. Each generator is bound to one schema. Use this when onboarding a new issuer or auditing how an existing schema is being populated.
lemma_get_proof_statusRead-onlyGet the verification status of a proof. NOTE: the v2 API does not yet expose a dedicated GET /v1/proofs/{id} endpoint, so this tool internally calls POST /v1/verified-attributes/query filtered by docHash (treating the verificationId returned from lemma_submit_proof as a docHash filter). Returns { status, circuitId, chainId, docHash } extracted from the matched item, or undefined if the verificationId is unknown. Status enum: received | verified | onchain-verified | rejected. Use the SDK's isVerified() helper (or check status === 'verified' || status === 'onchain-verified') to determine cryptographic validity.
| lemma_query_verified_attributes | Query cryptographically verified attributes from Lemma. Use this as the primary tool for finding documents whose attributes match given conditions (e.g., "subject's birthYear lt 2008"). Returns { results: Array<{ docHash, schema, issuerId, subjectId, attributes, isVerified, proof?: { status, circuitId, chainId }, disclosure? }>, hasMore }. The MCP layer enriches each item with an `isVerified` flag derived from `proof.status` (true when status is 'verified' or 'onchain-verified'). Use lemma_get_proof_status to monitor a specific proof; use lemma_get_schema to interpret the keys returned in `attributes`. | Read-only |
| lemma_get_schema | Retrieve a Lemma schema by its ID via GET /v1/schemas/{id}. A schema declares how documents of a given type are interpreted and normalized. Returns SchemaMeta { id, description? } with additionalProperties open — implementations commonly include a `normalize` artifact (WASM that maps raw documents to canonical form) and its content hash. Use this when you need to interpret attribute keys returned by lemma_query_verified_attributes. | Read-only |
| lemma_get_circuit | Retrieve a zero-knowledge proof circuit by its circuitId via GET /v1/circuits/{circuitId}. A circuit defines the constraints that proofs must satisfy and binds to a single schema. Returns CircuitMeta { circuitId, schema, description?, inputs?, verifier?: { type: 'onchain'|'offchain', address?, chainId? }, artifact?: { location: { type: 'ipfs'|'https', wasm, zkey } } }. Use this before lemma_submit_proof to confirm the circuit's schema, public inputs, and verifier configuration. Circuits are immutable; new variants get new circuitIds. | Read-only |
| lemma_get_generator | Retrieve a Lemma document generator by generatorId via GET /v1/doc-generators/{generatorId}. A generator describes how a class of source documents is produced (e.g., what fields a 'KYC-v2' issuer must populate). Returns GeneratorMeta { generatorId, schema, description?, language?, source?: { type: 'url', uri }, inputsSpec?, outputsSpec? }. Each generator is bound to one schema. Use this when onboarding a new issuer or auditing how an existing schema is being populated. | Read-only |
| lemma_get_proof_status | Get the verification status of a proof. NOTE: the v2 API does not yet expose a dedicated GET /v1/proofs/{id} endpoint, so this tool internally calls POST /v1/verified-attributes/query filtered by docHash (treating the verificationId returned from lemma_submit_proof as a docHash filter). Returns { status, circuitId, chainId, docHash } extracted from the matched item, or undefined if the verificationId is unknown. Status enum: received | verified | onchain-verified | rejected. Use the SDK's isVerified() helper (or check status === 'verified' || status === 'onchain-verified') to determine cryptographic validity. | Read-only |
Configuration
LEMMA_API_KEYRequiredSecretLemma API key (Bearer token). Get one at https://lemma.frame00.com/services
LEMMA_API_BASEOptional API base URL. Defaults to production endpoint.
| Name | Description | |
|---|---|---|
| LEMMA_API_KEY | Lemma API key (Bearer token). Get one at https://lemma.frame00.com/services | RequiredSecret |
| LEMMA_API_BASE | Optional API base URL. Defaults to production endpoint. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@lemmaoracle/mcp
@lemmaoracle/mcp is the Model Context Protocol (MCP) server that gives
AI agents access to Lemma's verifiable provenance layer — query
cryptographically verified attributes (zero-knowledge proofs, selective
disclosure, tamper-evident provenance) from confidential documents without
ever exposing the plaintext.
Models change. Proofs remain.
What is this?
This is an MCP server. MCP (Model Context Protocol) is the open protocol
for connecting AI agents to external tools and data sources, originally
released by Anthropic and now maintained as a community standard. This
package implements an MCP server using the official MCP SDK
(@modelcontextprotocol/sdk) and exposes a set of read-only tools for
querying Lemma's verifiable attribute API.
The current MVP exposes 5 read tools. Resources and prompts are
not exposed in v0.0.x; write tools (register_document, submit_proof)
are planned for Phase 2.
Quick start
Two ways to connect — pick whichever matches your agent setup.
Option 1 — Smithery (hosted gateway, zero install)
npx -y smithery mcp add lemmaoracle/lemma
Smithery proxies to the Lemma MCP endpoint at https://lemma--lemmaoracle.run.tools
and prompts for your Lemma API key. Best for trying the server quickly or for
agents that already speak Smithery. Server page:
smithery.ai/servers/lemmaoracle/lemma.
Option 2 — Claude Desktop with npx (stdio)
Add this to your Claude Desktop MCP config:
{
"mcpServers": {
"lemma": {
"command": "npx",
"args": ["-y", "@lemmaoracle/mcp"],
"env": {
"LEMMA_API_KEY": "YOUR_API_KEY"
}
}
}
}
Get an API key at https://lemma.frame00.com/services. LEMMA_API_BASE can
be omitted (defaults to production endpoint).
Try it in Glama Inspector
When trying this server in Glama's in-browser inspector (or any MCP inspector), you can use the demo key below. It is read-only and scoped to demo data (the same key is used by example-x402):
LEMMA_API_KEY=b6363aa6265322ed0d786a11d5b6d3264947052ca72deba4cbe1685d099af892
LEMMA_API_BASE=https://workers.lemma.workers.dev
For production access, request a key at https://lemma.frame00.com/services.
Tools (MCP tool list)
This server exposes the following MCP tools (no resources or prompts in the current MVP):
| Tool | Phase | Description |
|---|---|---|
lemma_query_verified_attributes |
MVP | Query cryptographically verified attributes from Lemma. Use this as the primary entry point for finding documents whose attributes match given conditions. |
lemma_get_schema |
MVP | Retrieve a Lemma schema (attribute structure) by ID. |
lemma_get_circuit |
MVP | Retrieve a ZK proof circuit (constraints + verifier) by ID. |
lemma_get_generator |
MVP | Retrieve a document generator (input/output spec) by ID. |
lemma_get_proof_status |
MVP | Get the verification status of a proof by its verificationId. |
lemma_register_document |
Phase 2 | Register a new document on Lemma. |
lemma_submit_proof |
Phase 2 | Submit a ZK proof for verification. |
Architecture
- MCP Server: this package — connects AI agents to the Lemma API via the Model Context Protocol.
- Lemma API: REST surface deployed on Cloudflare Workers, defined by OpenAPI v2.
- MCP SDK: this server is built on the official
@modelcontextprotocol/sdk(≥ 1.29). - License: Apache-2.0.
Privacy & data handling
Lemma is designed so that we never receive plaintext documents. The MCP server only transmits commitments, hashes, and ZK proofs to the Lemma API. See https://lemma.frame00.com/privacy for the full privacy policy.
Local development (contributors)
For contributors hacking on the MCP server itself, run it from a local
build of this monorepo. End users should use the npx config above.
git clone https://github.com/lemmaoracle/lemma.git
cd lemma
pnpm install
pnpm -F @lemmaoracle/mcp build
The bin entry produces packages/mcp/dist/index.js. Point Claude Desktop
at the absolute path:
{
"mcpServers": {
"lemma": {
"command": "node",
"args": ["/absolute/path/to/lemma/packages/mcp/dist/index.js"],
"env": {
"LEMMA_API_KEY": "YOUR_API_KEY"
}
}
}
}
Rebuild after changes with pnpm -F @lemmaoracle/mcp build and restart
Claude Desktop to reconnect. To point at a non-production API, add
"LEMMA_API_BASE": "https://..." to env.
Resources
- Documentation: this README + OpenAPI spec
- Homepage: https://lemma.frame00.com
- Issues: https://github.com/lemmaoracle/lemma/issues
Lemma MCP questions
How do I add Lemma MCP to Claude Code?
Run claude mcp add --env 'LEMMA_API_KEY=<YOUR_LEMMA_API_KEY>' mcp -- npx -y @lemmaoracle/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Lemma MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Lemma MCP provide?
It exposes 5 tools, including lemma_query_verified_attributes, lemma_get_schema, lemma_get_circuit, lemma_get_generator, lemma_get_proof_status.
Does the server expose my private document content?
No, the server is designed to never receive plaintext documents, only transmitting commitments, hashes, and ZK proofs.