MCP Protocol

Permission Protocol MCP Server Example

MCP Integration

The Permission Protocol SDK includes a built-in Model Context Protocol (MCP) server, enabling AI agents to interact with blockchain-based permissions, consents, and identities.

What is MCP?

MCP is an open protocol that standardizes how AI applications connect to external data sources and tools. Think of it as a universal adapter that lets AI agents:

• Query blockchain data (agreements, consents, DIDs)

• Resolve Web3 identities

• Access Permission Protocol without custom integrations

Starting the Server

There are two ways to start the MCP server:

Option 1: Command Line

Run directly with Bun from the project root:

bun run src/mcp/start.ts

This starts the server with default settings on http://localhost:3000/mcp.

Option 2: Programmatic

Import and call startMcpServer in your own code for custom configuration:

import { startMcpServer } from "@permission-io/protocol-sdk/mcp";

startMcpServer({
  rpcUrl: "https://sepolia.base.org", // Custom RPC (optional)
  chainId: 84532, // Base Sepolia
  port: 3000, // Server port
});

Configuration Options

Option	Default	Description
rpcUrl	Public RPC	Blockchain RPC endpoint
chainId	84532	Network ID (Base Sepolia)
port	3000	HTTP server port

Available Tools

Identity

Tool	Description	Input
get_address_did	Convert wallet address to DID	address (0x...)
get_did_document	Fetch on-chain DID document	did (did:pkh:0x...)
get_web3_domain	Resolve .ASK domain from address	address (0x...)

Agreements

Tool	Description	Input
get_agreements_by_did	Get user's agreements	did or walletAddress
get_agreement_data	Get agreement by ID	agreementId
get_agreements_count	Total agreements on-chain	—

Consents

Tool	Description	Input
get_consent_proofs_by_did	Get user's consent proofs	did or walletAddress
get_consent_record_data	Get consent record by ID	consentRecordId
get_consent_records_count	Total consent records	—
is_consent_records_revokable	Check revokability	consentRecordIds[]

Integration Examples

Google ADK (Python)

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, McpToolsetConfig

config = McpToolsetConfig(
    streamable_http_connection_params=StreamableHTTPConnectionParams(
        url="http://localhost:3000/mcp"
    )
)

toolset = MCPToolset.from_config(config=config, config_abs_path="")

agent = LlmAgent(
    model="gemini-2.0-flash",
    name="permission_agent",
    instruction="Query Permission Protocol for consents and agreements.",
    tools=[toolset]
)

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "permission-protocol": {
      "command": "bun",
      "args": ["run", "/path/to/permission-protocol-sdk/src/mcp/start.ts"]
    }
  }
}

Custom HTTP Client

const response = await fetch("http://localhost:3000/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    method: "tools/call",
    params: {
      name: "get_agreement_data",
      arguments: { agreementId: 1 },
    },
    id: 1,
  }),
});

Example Queries

Once connected, AI agents can answer questions like:

User Query	Tool Used
"What agreements has 0x123... created?"	get_agreements_by_did
"Show me consent record #5"	get_consent_record_data
"What's the DID for this wallet?"	get_address_did
"Can consent records 1, 2, 3 be revoked?"	is_consent_records_revokable
"What's the web3 domain for 0xabc...?"	get_web3_domain

LimitationsRead-Only: The MCP server only exposes read operations. Creating agreements or consents requires wallet signing via the SDK directly.

• Supported Chain: Base Sepolia (84532) only. Base mainnet contracts coming soon.

• Address Format: Must be valid Ethereum addresses (0x + 40 hex chars)

• DID Format: Must follow did:pkh:0x... format

• Indexer Delay: Graph-based queries may have slight delays after on-chain transactions