Tctc MCP server

tctc-mcp

An MCP server exposing ERC-7303 (Token-Controlled Token Circulation) roles to AI agents: agents check their own on-chain permissions, and human principals grant/revoke them by minting/burning control tokens — no permission server required.

Status: v0.3.4 — adds timed roles with gasless auto-expiry (below), on top of v0.2's IERC7303 auto-discovery; published on npm (tctc-mcp), unit-tested and verified end-to-end against the Sepolia demo deployment (grant → check → revoke → check, and grant-for-75s → auto-expiry, through a real MCP client).

Demo (60 seconds)

A human grants an AI agent a minting permission; the agent verifies it on-chain and mints an NFT. The human burns the role token — and the agent instantly loses the capability. Live on Sepolia, no permission server involved.

Quick start

The package is published on npm, so no clone or build is needed — npx fetches and runs it directly:

# 1. Get a config. The secret-free Sepolia demo config needs no API keys:
curl -fsSLO https://raw.githubusercontent.com/kofujimura/tctc-mcp/main/examples/config.sepolia.agent.json

# 2. Register with your MCP client, e.g. Claude Code
#    (read-only mode: only query tools are registered)
claude mcp add tctc -- npx -y tctc-mcp --config "$PWD/config.sepolia.agent.json"

# Admin mode (principal side): grant_role / revoke_role also registered.
# Provide the issuer key ONLY via the environment:
claude mcp add tctc-admin --env TCTC_ADMIN_PRIVATE_KEY=0x... \
  -- npx -y tctc-mcp --config "$PWD/config.sepolia.json"

Or in a project-scoped .mcp.json:

{ "mcpServers": { "tctc": { "command": "npx",
    "args": ["-y", "tctc-mcp", "--config", "examples/config.sepolia.agent.json"] } } }

A fuller registration example is in examples/claude.mcp.json. The admin private key is only ever read from the TCTCADMINPRIVATE_KEY environment variable; configs containing anything that looks like a private key are rejected at startup.

Using tctc-mcp from your own app

The only supported entry point is the tctc-mcp bin — spawn it via npx --no-install tctc-mcp (or node_modules/.bin/tctc-mcp). Never reference the package's dist/ files directly: they are internal, their layout is unversioned, and the package's exports field refuses deep imports. A minimal MCP-SDK client example (the pattern for a web backend) is in examples/client-stdio.mjs; the release pipeline verifies the packed bin end-to-end (scripts/verify-pack.mjs).

Web application starter

Want to see tctc-mcp protecting a real API route?

tctc-openai-starter is a standalone Next.js starter that verifies wallet ownership with Sign-In with Ethereum, checks the configured role through tctc-mcp, and calls OpenAI only when the on-chain gate grants access.

Use it as a GitHub template.

Token-gating any MCP server: tctc-gate

The reverse direction lives in this repo too: tctc-gate (npm) is a transparent stdio proxy that puts an ERC-7303 role check in front of any existing MCP server, unmodified — deny comes back with a grant URL that opens the dashboard pre-filled. tctc-mcp lets agents ask about roles; tctc-gate enforces them at the boundary:

npx -y tctc-gate --config gate.json -- npx -y some-mcp-server …

Tools

Shortened. The full README is on GitHub.