Zero-Knowledge MCP

Build and publish MCP servers where credential values never exist anywhere.

Documentation

• 📚 Tutorial — Build your first Zero-Knowledge tool step by step
• 🛠️ Custom Environments — Using uv, standard pip, or a custom virtual environment instead of Poetry

---

The Paradigm

Every MCP server published today stores credentials somewhere reachable:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_actual_token_here"
      }
    }
  }
}

The credential value is in the config file, in the environment, in process memory. A prompt injection attack, a compromised plugin, or a context leak can reach it.

Zero-Knowledge MCP fixes this. The Claude Desktop config becomes:

{
  "mcpServers": {
    "zero-knowledge-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/zero-knowledge-mcp/server.py"]
    }
  }
}

No env block. No credential values. The server gets everything from the proxy.

---

Prerequisites

The AgentSecrets CLI must be installed and running. Install it once on your machine:

# Homebrew (macOS / Linux) — recommended
brew install The-17/tap/agentsecrets

# npm
npm install -g @the-17/agentsecrets

# pip
pip install agentsecrets-cli

Then initialize your account:

agentsecrets init

---

Getting Started

Step 1: Install Poetry (if not already installed)

curl -sSL https://install.python-poetry.org | python3 -

Step 2: Clone and install

git clone https://github.com/The-17/zero-knowledge-mcp
cd zero-knowledge-mcp
make install

Step 3: Set your credentials in AgentSecrets

agentsecrets secrets set GITHUB_TOKEN=ghp_your_token
agentsecrets secrets set DEMO_API_KEY=your_key

Step 4: Add domains to the allowlist

agentsecrets workspace allowlist add api.github.com
agentsecrets workspace allowlist add wttr.in
agentsecrets workspace allowlist add api.example.com

Step 5: Start the proxy

agentsecrets proxy start

Step 6: Add to Claude Desktop

Edit your claude_desktop_config.json. Notice the complete absence of an env block:

{
  "mcpServers": {
    "zero-knowledge-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/zero-knowledge-mcp/server.py"]
    }
  }
}

If you are using Poetry, replace "python" with "poetry" and args with ["run", "python", "/absolute/path/to/server.py"]. See Custom Environments for other setups.

Step 7: Ask Claude to use a tool

"Can you list my public GitHub repositories?" "What is the weather in London right now?"

---

How to Add Your Own Tools

Copy this blank tool structure into a new file in tools/:

from agentsecrets import AgentSecrets
from .base import handle_errors

client = AgentSecrets()

@handle_errors
async def my_new_tool(argument: str) -> dict:
    """
    Clear description of what this tool does.
    This docstring is what the AI agent reads to decide when to call this tool.
    Make it specific.
    """
    response = await client.async_call(
        "https://api.example.com/endpoint",
        bearer="SECRET_KEY_NAME"
    )
    return response.json()

No os.getenv. No manual auth headers. No credential values anywhere.

Then register it in tools/__init__.py:

def register_tools(mcp):
    mcp.tool()(my_new_tool)

See TUTORIAL.md for a full walkthrough including all six injection styles.

---

How the Credential Model Works

Tool Request  →  AgentSecrets SDK  →  Local Proxy  →  OS Keychain  →  Upstream API
 (KEY_NAME)        (intercept)       (resolution)     (injection)

1. Your tool calls client.async_call() with a key name — never the value
2. The SDK routes the request to the local proxy at localhost:8765
3. The proxy resolves the key name from your OS keychain
4. The proxy injects the value at the transport layer and forwards the request
5. The API responds — the proxy returns only the response to your tool

Your Python process never saw, held, or touched the actual credential value.

For a deep dive, see the AgentSecrets Architecture docs.

---

What This Closes

• Prompt injection — agents cannot leak credentials they never held
• Config file exposure — your claude_desktop_config.json contains no credential values and can be safely shared
• Context leakage — even if a tool dumps its full context, no credential values are present to leak
• Plugin compromise — a compromised dependency cannot access values it cannot reach

---

Built on AgentSecrets

Zero-Knowledge MCP is built on the AgentSecrets SDK. AgentSecrets provides the local proxy, the CLI, and the zero-knowledge infrastructure that makes this paradigm possible.

CLI: github.com/The-17/agentsecrets SDK: github.com/The-17/agentsecrets-sdk

---

Contributing

git clone https://github.com/The-17/zero-knowledge-mcp.git
cd zero-knowledge-mcp
make install
make test

Found a bug? Open an issue Have an idea? Start a discussion