{"id":44836183,"url":"https://github.com/capiscio/capiscio-mcp-python","last_synced_at":"2026-02-17T01:36:24.933Z","repository":{"id":333279664,"uuid":"1135272755","full_name":"capiscio/capiscio-mcp-python","owner":"capiscio","description":"CapiscIO MCP Guard - Secure your MCP tools with agent-to-server authentication, authorization, and audit logging","archived":false,"fork":false,"pushed_at":"2026-02-04T18:31:52.000Z","size":1160,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-05T05:44:09.251Z","etag":null,"topics":["a2a","agent-to-agent","ai-agents","audit-logging","authentication","authorization","llm","mcp","model-context-protocol","python","security","trust"],"latest_commit_sha":null,"homepage":"https://capisc.io/products/mcp-guard","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/capiscio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T21:50:33.000Z","updated_at":"2026-02-04T18:31:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/capiscio/capiscio-mcp-python","commit_stats":null,"previous_names":["capiscio/capiscio-mcp-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/capiscio/capiscio-mcp-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-mcp-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-mcp-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-mcp-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-mcp-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capiscio","download_url":"https://codeload.github.com/capiscio/capiscio-mcp-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-mcp-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29529513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T00:57:22.232Z","status":"ssl_error","status_checked_at":"2026-02-17T00:54:25.811Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","agent-to-agent","ai-agents","audit-logging","authentication","authorization","llm","mcp","model-context-protocol","python","security","trust"],"created_at":"2026-02-17T01:36:24.412Z","updated_at":"2026-02-17T01:36:24.913Z","avatar_url":"https://github.com/capiscio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CapiscIO MCP Guard\n\nTool-level security for Model Context Protocol servers.\n\n[![PyPI version](https://badge.fury.io/py/capiscio-mcp.svg)](https://badge.fury.io/py/capiscio-mcp)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n**MCP Guard** provides trust badges and identity verification for [Model Context Protocol (MCP)](https://modelcontextprotocol.io) tool calls. It implements:\n\n- **RFC-006**: MCP Tool Authority and Evidence\n- **RFC-007**: MCP Server Identity Disclosure and Verification\n\n## Installation\n\n```bash\npip install capiscio-mcp\n```\n\nFor MCP SDK integration (FastMCP wrapper):\n\n```bash\npip install capiscio-mcp[mcp]\n```\n\n## Why MCP Guard?\n\nMCP servers expose powerful tools to autonomous agents—file systems, databases, APIs. But MCP itself doesn't define how to:\n\n- **Authenticate** which agent is calling a tool\n- **Authorize** whether that agent should have access\n- **Audit** what happened for post-incident review\n\nMCP Guard solves this with:\n\n| Feature | Description |\n|---------|-------------|\n| **@guard decorator** | Protect tools with trust-level requirements |\n| **Evidence logging** | Cryptographic audit trail for every invocation |\n| **Server identity** | Verify MCP servers before connecting |\n| **Server registration** | Generate keypairs and register server DIDs |\n| **Trust levels** | 0 (self-signed) → 4 (extended validation) |\n\n## Quickstart 1: Server-Side (Tool Guarding)\n\nProtect your MCP tools with trust-level requirements:\n\n```python\nfrom capiscio_mcp import guard\n\n@guard(min_trust_level=2)\nasync def read_database(query: str) -\u003e list[dict]:\n    \"\"\"Only agents with Trust Level 2+ can execute this tool.\"\"\"\n    # ... database query logic\n    pass\n\n# Sync version available\nfrom capiscio_mcp import guard_sync\n\n@guard_sync(min_trust_level=2)\ndef read_database_sync(query: str) -\u003e list[dict]:\n    pass\n```\n\n### With Full Configuration\n\n```python\nfrom capiscio_mcp import guard, GuardConfig\n\nconfig = GuardConfig(\n    min_trust_level=2,\n    trusted_issuers=[\"did:web:registry.capisc.io\"],\n    allowed_tools=[\"read_*\", \"list_*\"],\n    require_badge=True,  # Deny anonymous access\n)\n\n@guard(config=config)\nasync def execute_query(sql: str) -\u003e list[dict]:\n    pass\n```\n\n## Quickstart 2: Client-Side (Server Verification)\n\nVerify the identity of MCP servers you connect to:\n\n```python\nfrom capiscio_mcp import verify_server, ServerState\n\nresult = await verify_server(\n    server_did=\"did:web:mcp.example.com\",\n    server_badge=\"eyJhbGc...\",\n    transport_origin=\"https://mcp.example.com\",\n)\n\nif result.state == ServerState.VERIFIED_PRINCIPAL:\n    print(f\"Trusted server at Level {result.trust_level}\")\nelif result.state == ServerState.DECLARED_PRINCIPAL:\n    print(\"Server identity declared but not verified\")\nelif result.state == ServerState.UNVERIFIED_ORIGIN:\n    print(\"Warning: Server did not disclose identity\")\n```\n\n## Quickstart 3: Server Registration\n\nRegister your MCP server's identity with the CapiscIO registry:\n\n```python\nfrom capiscio_mcp import setup_server_identity\n\n# One-step setup: generate keys + register with registry\nresult = await setup_server_identity(\n    server_id=\"550e8400-e29b-41d4-a716-446655440000\",  # From dashboard\n    api_key=\"sk_live_...\",  # Registry API key\n    ca_url=\"https://registry.capisc.io\",  # Optional, defaults to production\n    output_dir=\"./keys\",\n)\n\nprint(f\"Server DID: {result['did']}\")\n# did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK\nprint(f\"Private key saved to: {result['private_key_path']}\")\n```\n\n### Step-by-Step Registration\n\n```python\nfrom capiscio_mcp import generate_server_keypair, register_server_identity\n\n# Step 1: Generate keypair\nkeys = await generate_server_keypair(output_dir=\"./keys\")\n\n# Step 2: Register with registry\nawait register_server_identity(\n    server_id=\"550e8400-e29b-41d4-a716-446655440000\",\n    api_key=\"sk_live_...\",\n    did=keys[\"did_key\"],\n    public_key=keys[\"public_key_pem\"],\n    ca_url=\"https://registry.capisc.io\",  # Optional, defaults to production\n)\n```\n\n## MCP SDK Integration\n\nFor seamless integration with the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), install with the `mcp` extra:\n\n```bash\npip install capiscio-mcp[mcp]\n```\n\n### Server with FastMCP Wrapper\n\nCreate an MCP server with built-in trust enforcement:\n\n```python\nfrom capiscio_mcp.integrations.mcp import CapiscioMCPServer\n\nserver = CapiscioMCPServer(\n    name=\"filesystem\",\n    did=\"did:web:mcp.example.com:servers:filesystem\",\n    badge=\"eyJhbGc...\",  # From CapiscIO registry\n)\n\n@server.tool(min_trust_level=2)\nasync def read_file(path: str) -\u003e str:\n    \"\"\"Only agents with Trust Level 2+ can read files.\"\"\"\n    with open(path) as f:\n        return f.read()\n\n@server.tool(min_trust_level=0)\nasync def list_files(directory: str) -\u003e list[str]:\n    \"\"\"Any authenticated agent can list files.\"\"\"\n    import os\n    return os.listdir(directory)\n\n# Run the server (stdio transport)\nserver.run()\n```\n\n### Client with Trust Verification\n\nConnect to MCP servers via stdio transport:\n\n```python\nfrom capiscio_mcp.integrations.mcp import CapiscioMCPClient\n\nasync with CapiscioMCPClient(\n    command=\"python\",\n    args=[\"my_mcp_server.py\"],\n    min_trust_level=1,\n    badge=\"eyJhbGc...\",  # Your client badge\n) as client:\n    # List available tools\n    tools = await client.list_tools()\n    print(f\"Available tools: {[t['name'] for t in tools]}\")\n    \n    # Call a tool\n    result = await client.call_tool(\"read_file\", {\"path\": \"/data/config.json\"})\n    print(result)\n```\n\n## Core Connection Modes\n\nMCP Guard connects to capiscio-core for cryptographic operations:\n\n### Embedded Mode (Default)\n\nSDK automatically downloads and manages the core binary:\n\n```bash\npip install capiscio-mcp\n# Just works! Binary downloaded on first use.\n```\n\n### External Mode\n\nConnect to a separately managed core service:\n\n```bash\n# Start core in another terminal\ncapiscio mcp serve --listen localhost:50051\n\n# SDK connects to external core\nexport CAPISCIO_CORE_ADDR=\"localhost:50051\"\n```\n\n## Trust Levels\n\nPer RFC-002 v1.4:\n\n| Level | Name | Validation | Use Case |\n|-------|------|------------|----------|\n| 0 | Self-Signed (SS) | None, `did:key` issuer | Local dev, testing, demos |\n| 1 | Registered (REG) | Account registration | Development, internal agents |\n| 2 | Domain Validated (DV) | DNS/HTTP challenge | Production, B2B agents |\n| 3 | Organization Validated (OV) | DUNS/legal entity | High-trust production |\n| 4 | Extended Validated (EV) | Manual review + legal | Regulated industries |\n\n## Evidence Logging\n\nEvery tool invocation—allowed or denied—produces an evidence record:\n\n```python\nfrom capiscio_mcp import guard, GuardError\n\n@guard(min_trust_level=2)\nasync def sensitive_operation(data: dict) -\u003e dict:\n    pass\n\ntry:\n    result = await sensitive_operation(data={\"key\": \"value\"})\nexcept GuardError as e:\n    # Evidence logged even on denial\n    print(f\"Denied: {e.reason}\")\n    print(f\"Evidence ID: {e.evidence_id}\")  # For audit trail\n```\n\nEvidence includes:\n- Tool name and parameters hash (not raw params—PII safe)\n- Caller identity (agent DID, badge JTI, auth level)\n- Decision and reason\n- Timestamp and unique evidence ID\n\n## Configuration Reference\n\n### GuardConfig\n\n```python\nfrom capiscio_mcp import GuardConfig\n\nconfig = GuardConfig(\n    min_trust_level=2,        # Minimum trust level (0-4)\n    accept_level_zero=False,  # Accept self-signed badges?\n    trusted_issuers=[         # List of trusted issuer DIDs\n        \"did:web:registry.capisc.io\",\n    ],\n    allowed_tools=[           # Glob patterns for allowed tools\n        \"read_*\",\n        \"list_*\",\n    ],\n    require_badge=True,       # Deny anonymous/API key access\n    policy_version=\"v1.0\",    # Policy version for tracking\n)\n```\n\n### VerifyConfig\n\n```python\nfrom capiscio_mcp import VerifyConfig\n\nconfig = VerifyConfig(\n    trusted_issuers=[...],    # Trusted issuer DIDs\n    min_trust_level=2,        # Minimum required level\n    accept_level_zero=False,  # Accept self-signed servers?\n    offline_mode=False,       # Skip revocation checks?\n    skip_origin_binding=False,  # Skip host/path binding?\n)\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `CAPISCIO_CORE_ADDR` | External core address | (embedded mode) |\n| `CAPISCIO_SERVER_ORIGIN` | Server origin for guard | (auto-detect) |\n| `CAPISCIO_LOG_LEVEL` | Logging verbosity | `info` |\n\n## API Reference\n\n### Guard (RFC-006)\n\n- `guard(config=None, min_trust_level=None, tool_name=None)` — Async decorator\n- `guard_sync(...)` — Sync decorator\n- `evaluate_tool_access(tool_name, params, credential, config)` — Low-level API\n- `compute_params_hash(params)` — Deterministic parameter hashing\n- `GuardConfig` — Configuration dataclass\n- `GuardResult` — Evaluation result dataclass\n- `GuardError` — Exception for denied access\n\n### Server (RFC-007)\n\n- `verify_server(server_did, server_badge, transport_origin, endpoint_path, config)` — Async verification\n- `verify_server_sync(...)` — Sync verification\n- `verify_server_strict(...)` — Raises ServerVerifyError on any verification failure\n- `parse_http_headers(headers)` — Extract identity from HTTP headers\n- `parse_jsonrpc_meta(meta)` — Extract identity from MCP _meta\n- `VerifyConfig` — Configuration dataclass\n- `VerifyResult` — Verification result dataclass\n- `ServerVerifyError` — Exception for verification failures\n\n### Registration (Server Identity)\n\n- `generate_server_keypair(key_id, output_dir)` — Generate Ed25519 keypair\n- `generate_server_keypair_sync(...)` — Sync version\n- `register_server_identity(server_id, api_key, did, public_key, ca_url)` — Register DID with registry\n- `register_server_identity_sync(...)` — Sync version\n- `setup_server_identity(server_id, api_key, ca_url, output_dir, key_id)` — Combined setup\n- `setup_server_identity_sync(...)` — Sync version\n- `RegistrationError` — Exception for registration failures\n- `KeyGenerationError` — Exception for key generation failures\n\n### Types\n\n- `Decision` — ALLOW / DENY\n- `AuthLevel` — ANONYMOUS / API_KEY / BADGE\n- `DenyReason` — Enumeration of denial reasons\n- `TrustLevel` — Trust levels 0-4 per RFC-002\n- `ServerState` — VERIFIED_PRINCIPAL / DECLARED_PRINCIPAL / UNVERIFIED_ORIGIN\n- `ServerErrorCode` — Enumeration of verification error codes\n\n### MCP SDK Integration (optional)\n\nRequires `pip install capiscio-mcp[mcp]`:\n\n- `CapiscioMCPServer(name, did, badge, ...)` — FastMCP wrapper with trust enforcement\n- `CapiscioMCPServer.tool(min_trust_level=...)` — Decorator for guarded tools\n- `CapiscioMCPServer.run(transport=\"stdio\")` — Run the server\n- `CapiscioMCPClient(command, args, ...)` — Client for stdio transport*\n- `CapiscioMCPClient.call_tool(name, args)` — Call a tool on the server\n- `CapiscioMCPClient.list_tools()` — List available tools\n\n*Note: Server identity verification in `CapiscioMCPClient` requires MCP SDK support for `_meta` passthrough in initialize responses. This is not yet available, so `min_trust_level` and `fail_on_unverified` parameters are currently not enforced. Server-side trust enforcement via `@server.tool(min_trust_level=...)` works fully.\n\n## Documentation\n\n- [RFC-006: MCP Tool Authority and Evidence](https://docs.capisc.io/rfcs/006)\n- [RFC-007: MCP Server Identity Disclosure](https://docs.capisc.io/rfcs/007)\n- [Server Registration Guide](https://docs.capisc.io/mcp-guard/guides/server-registration)\n- [Server-Side Guide](https://docs.capisc.io/mcp-guard/guides/server-side)\n- [Client-Side Guide](https://docs.capisc.io/mcp-guard/guides/client-side)\n- [Evidence Logging Guide](https://docs.capisc.io/mcp-guard/guides/evidence)\n\n## Development\n\n```bash\n# Clone repository\ngit clone https://github.com/capiscio/capiscio-mcp-python.git\ncd capiscio-mcp-python\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest -v\n\n# Run tests with coverage\npytest --cov=capiscio_mcp --cov-report=html\n\n# Type checking\nmypy capiscio_mcp\n\n# Linting\nruff check capiscio_mcp\n```\n\n## License\n\nApache License 2.0\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapiscio%2Fcapiscio-mcp-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapiscio%2Fcapiscio-mcp-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapiscio%2Fcapiscio-mcp-python/lists"}