# MCP Protocol

## MCP Integration

The Permission Protocol SDK includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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:

```bash
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:

```typescript
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)

```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`):

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

#### Custom HTTP Client

```typescript
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`              |

### Limitations**Read-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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.permission.ai/permission-protocol/v1-protocol/mcp-protocol.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.