{"type":"text/markdown","content":"# MCP Connection Guide\n\nConnect AI agent platforms (Claude Desktop, OpenClaw, Cursor) to IdentyClaw's Model Context Protocol (MCP) server. MCP exposes documentation and discovery through `list_resources` and `get_resource` only — it does not store credentials or perform API login.\n\n**Reference (IdentyClaw)** — MCP `https://api.identyclaw.com/mcp`, REST resources under `https://api.identyclaw.com/api/mcp/…` (this deployment; OpenAPI in [`api-docs/swagger.json`](../api-docs/swagger.json)).\n\nAuthenticated API calls (`POST /api/login`, HOLA, identity) use the REST API from the agent host. See [login-authentication.md](login-authentication.md) and [mcp-auth-tools.md](mcp-auth-tools.md).\n\n## Access patterns\n\n| You have… | Use |\n|-----------|-----|\n| MCP client (OpenClaw, Claude Desktop, Cursor) | Register `https://api.identyclaw.com/mcp` in `mcpServers`; call tools `list_resources` / `get_resource` |\n| `curl` or shell HTTP only | `GET /.well-known/mcp`, `GET /api/mcp/resources`, `GET /api/mcp/resource/{uri}` |\n\n### Shell and curl agents\n\nMCP **tool names are not URL paths**. Do not call `/mcp/resources` or `/mcp/resource/...` — those paths do not exist.\n\n| MCP tool (client only) | REST equivalent (curl) |\n|------------------------|-------------------------|\n| `list_resources` | `GET /api/mcp/resources` |\n| `get_resource` | `GET /api/mcp/resource/{uri}` |\n\nDo **not** `GET` or `curl` `https://api.identyclaw.com/mcp` for documentation. That URL is MCP Streamable HTTP transport only; use an MCP client registered on `/mcp`, or the REST paths above.\n\n`Mcp-Session-Id` is assigned by the MCP client after `initialize`. It is not API login and is not obtained from a user.\n\n### Verification (copy-paste)\n\n```bash\ncurl https://api.identyclaw.com/health\ncurl https://api.identyclaw.com/.well-known/mcp\ncurl https://api.identyclaw.com/api/mcp/resources\ncurl https://api.identyclaw.com/api/mcp/resource/guide:enrollment\n```\n\n### Minimal client config\n\n```json\n{\n  \"mcpServers\": {\n    \"IdentyClaw\": {\n      \"url\": \"https://api.identyclaw.com/mcp\",\n      \"description\": \"IdentyClaw docs and discovery (public)\"\n    }\n  }\n}\n```\n\n---\n\n## Claude Desktop Configuration\n\n### Step 1: Locate Your Configuration File\n\n**macOS:**\n```javascript\n~/Library/Application Support/Claude/claude_desktop_config.json;\n```\n\n**Windows:**\n```\n%APPDATA%\\Claude\\claude_desktop_config.json\n```\n\n**Linux:**\n```javascript\n~/.config/Claude/claude_desktop_config.json;\n```\n\n### Step 2: Add IDClawserver MCP Configuration\n\nEdit `claude_desktop_config.json` and add the MCP server under the `mcpServers` section:\n\n```json\n{\n  \"mcpServers\": {\n  \"IdentyClaw\": {\n  \"url\": \"https://api.identyclaw.com/mcp\",\n  \"description\": \"IdentyClaw API - IdentyClaw Passport identity verification and DID resolution\"\n}\n}\n}\n```\n\n### Step 3: Restart Claude Desktop\n\nClose and reopen Claude Desktop. The MCP server should now be available.\n\n### Step 4: Verify Connection\n\nIn Claude, ask:\n```\nWhat MCP resources are available from IdentyClaw?\n```\n\nClaude will call the `list_resources` tool and show you available resources.\n\nYou can also verify over HTTP:\n\n```bash\ncurl https://api.identyclaw.com/api/mcp/resources\ncurl https://api.identyclaw.com/api/mcp/resource/guide:enrollment\n```\n\n---\n\n## Cursor Configuration\n\nCursor agents use the same IdentyClaw MCP server as Claude Desktop. MCP provides **documentation only** — implement API login and HOLA signing on the host per [`mcp-auth-tools.md`](mcp-auth-tools.md).\n\n### Step 1: Add MCP server\n\nIn Cursor **Settings → MCP** (or project `.cursor/mcp.json`), add:\n\n```json\n{\n  \"mcpServers\": {\n    \"IdentyClaw\": {\n      \"url\": \"https://api.identyclaw.com/mcp\",\n      \"description\": \"IdentyClaw API docs — enrollment, HOLA, OpenAPI\"\n    }\n  }\n}\n```\n\n### Step 2: Bootstrap the agent\n\nAsk the agent to:\n\n1. Fetch `doc:reference:agent-frameworks` — confirms Cursor uses the generic MCP + manual enrollment path\n2. Fetch `doc:skills` — runnable cheat sheet for JWT and HOLA\n3. Fetch `guide:enrollment` when enrolling a new Passport\n\n### Step 3: Authenticated API calls\n\nCursor does not store your NEAR key. Options:\n\n- Shell login script writing `jwt_token` to `~/.identyclaw/jwt.txt` (see [mcp-auth-tools.md](mcp-auth-tools.md))\n- Node `@rodit/hola-client` for HOLA create after login\n- `POST /api/identity/verify` for peer verify (public — no JWT)\n\n### Step 4: Optional Cursor Agent Skill\n\nFor persistent workflow hints, add a project rule or copy patterns from [`references/skills.md`](skills.md). Runtime-specific guides: [`agent-frameworks.md`](agent-frameworks.md).\n\nVerify MCP over HTTP without the IDE:\n\n```bash\ncurl https://api.identyclaw.com/api/mcp/resource/doc:reference:agent-frameworks\ncurl https://api.identyclaw.com/api/mcp/resource/doc:skills\n```\n\n---\n\n## Available MCP Resources\n\n| Resource URI | Type | Purpose |\n|--------------|------|---------|\n| `openapi:swagger` | JSON | Complete API specification |\n| `guide:api` | JSON | Comprehensive API guide with examples |\n| `skills:skills` | Markdown | Core workflows |\n| `guide:enrollment` | JSON | Step-by-step enrollment guide |\n| `guide:troubleshooting` | JSON | Common errors and solutions |\n| `guide:why-IdentyClaw` | Markdown | Value proposition and use cases |\n| `onboarding:near` | JSON | NEAR account setup instructions |\n| `readme:main` | JSON | Service overview |\n| `health:status` | JSON | Server health and status |\n| `config:default` | JSON | Server configuration |\n| `policy:terms` | Markdown | Terms of Service |\n| `policy:privacy` | Markdown | Privacy Policy |\n| `policy:data-retention` | Markdown | Data Retention Policy |\n| `policy:service-info` | JSON | Service contact information |\n| `jsonld:context` | JSON-LD | RODiT JSON-LD context |\n| `jsonld:contract-metadata` | JSON-LD | Smart contract metadata |\n| `did:resolve:{tokenId}` | JSON | Resolve DID document by token ID (`did:rodit`, experimental) |\n| `doc:reference:did-rodit-method` | Markdown | `did:rodit` method specification (RFC alignment) |\n| `doc:reference:holanonce-api` | Markdown | `GET /api/holanonce16ts` JSON: `noncetsHex`, `timestamp`, `length`, `algorithm`, `requestId` |\n| `doc:reference:token-metadata` | Markdown | IdentyClaw Passport metadata; facial trait categories (authoritative) |\n| `doc:reference:mcp-auth-tools` | Markdown | Client-side agent authentication (truncated JWT, SDK, file storage) |\n| `doc:reference:login-authentication` | Markdown | API login flow and JWT usage |\n| `doc:reference:mcp-connection-guide` | Markdown | This document |\n| `doc:discovery` | Markdown | MCP discovery index — start here for agent onboarding |\n| `doc:reference:identyclaw-skill` | Markdown | ClawHub skill install pointer and bundled references |\n| `doc:reference:finding-agents` | Markdown | Paginated discovery → full identity → impersonation guard |\n| `doc:reference:inter-agent-communication` | Markdown | Email + HOLA patterns for channel outreach |\n| `doc:reference:hola-subagent-authentication` | Markdown | Subagent HOLA + delegation verification |\n| `doc:reference:openclaw-integration-guide` | Markdown | Wire Passport webhooks to OpenClaw `/hooks/agent` |\n| `doc:reference:hola-howto` | Markdown | Build and send HOLA in ~5 minutes |\n| `doc:reference:verify-hola-recipes` | Markdown | Verify before execute — copy-paste HOLA verifier recipes |\n| `doc:reference:collaboration-envelope` | Markdown | Normative JSON envelope for multi-channel tasks |\n| `doc:reference:agent-frameworks` | Markdown | OpenClaw / Hermes / IronClaw / NanoClaw / Cursor routing |\n| `doc:reference:hermes-integration-guide` | Markdown | Hermes enrollment and API patterns |\n| `doc:reference:ironclaw-integration-guide` | Markdown | IronClaw MCP + host sidecar |\n| `doc:reference:nanoclaw-integration-guide` | Markdown | NanoClaw container enrollment |\n| `token:facial-categories` | JSON | Discovery stub → `doc:reference:token-metadata#facial-token-id-encoding` |\n\nLive registry: `GET /api/mcp/resources`. For client-side JWT storage after login, see [mcp-auth-tools.md](mcp-auth-tools.md).\n\n---\n\n## Webhook Testing\n\n> **Canonical guide:** MCP `doc:reference:openclaw-integration-guide` or [`openclaw-integration-guide.md`](openclaw-integration-guide.md) — Passport `webhook_url`, `/hooks/agent` vs `/hooks/wake`, receiver checklist.\n\nThe `/api/testhola` endpoint supports development webhook testing.\n\n### Development Webhook Behavior\n\nIn development mode, successful HOLA validation triggers webhook delivery:\n\n**Event Type:** `testhola_validation_success`\n\n**Webhook Endpoints:**\n- `/hooks/wake` - Trigger immediate heartbeat (enqueue system event for main session)\n- `/hooks/agent` - Run isolated agent task (execute background tasks with optional reply to messaging channels)\n\n**Webhook Payload:**\n```json\n{\n  \"event\": \"testhola_validation_success\",\n  \"data\": {\n  \"peerTokenId\": \"abc123def456\",\n  \"serverTokenId\": \"xyz789uvw012\",\n  \"recipient\": \"MUNDO\",\n  \"timestamp\": \"2026-04-24T18:30:00.000Z\",\n  \"endpoint\": \"/api/testhola\"\n}\n}\n```\n\n**Configuration:**\nConfigure your webhook URL in your IdentyClaw Passport metadata (`webhook_url` field) to receive webhook events.\n\n**Use Case:**\nThis allows testing webhook delivery during development without main deployment. The webhook is only sent in development mode, making it safe for testing webhook infrastructure.\n\n---\n\n## Using MCP Resources in Claude\n\n### Example 1: Get the OpenAPI Schema\n\n```\nClaude: What endpoints does IdentyClaw provide?\n```\n\nClaude will fetch `openapi:swagger` and show you the complete API specification.\n\n### Example 2: Understand Authentication\n\n```\nClaude: How do I authenticate with IdentyClaw?\n```\n\nClaude will fetch `guide:api` and `skills:skills` to explain the authentication flow.\n\n### Example 3: Set Up a NEAR Account\n\n```\nClaude: I need to set up a NEAR account to get an IdentyClaw Passport. What are the steps?\n```\n\nClaude will fetch `onboarding:near` and `guide:enrollment` to provide complete instructions.\n\n### Example 4: Troubleshoot an Error\n\n```\nClaude: I'm getting error 035: PeerEd25519SignatureVerificationFailure. What does this mean?\n```\n\nClaude will fetch `guide:troubleshooting` and explain the cause and solution.\n\n---\n\n## Direct HTTP Access to MCP Resources\n\nIn addition to using MCP tools, you can access MCP resources directly via HTTP endpoints. This is useful for:\n- Testing resources without an MCP client\n- Integrating with non-MCP applications\n- Debugging and manual verification\n- Scripting and automation\n\n### Resource Access Pattern\n\n**List all resources:**\n```javascript\nGET /api/mcp/resources;\n```\n\n**Fetch a specific resource by URI:**\n```javascript\nGET /api/mcp/resource/{uri};\n```\n\n**Important:** The URI from the resource list is used **as-is** in the URL path. No URL encoding is needed for the colon (`:`) character.\n\n### Examples\n\n#### 1. List All Available Resources\n\n```bash\ncurl https://api.identyclaw.com/api/mcp/resources\n```\n\n**Response:**\n```json\n{\n  \"resources\": [\n  {\n    \"uri\": \"openapi:swagger\",\n    \"name\": \"OpenAPI Schema\",\n    \"type\": \"application/json\"\n  },\n  {\n    \"uri\": \"skills:skills\",\n    \"name\": \"Skills Documentation\",\n    \"type\": \"text/markdown\"\n  },\n  ...,\n}\n```\n\n#### 2. Fetch the Skills Documentation\n\n```bash\ncurl https://api.identyclaw.com/api/mcp/resource/skills:skills\n```\n\n**Response:** Returns the full `references/skills.md` content as markdown.\n\n#### 3. Fetch the OpenAPI Schema\n\n```bash\ncurl https://api.identyclaw.com/api/mcp/resource/openapi:swagger\n```\n\n**Response:** Returns the complete OpenAPI specification as JSON.\n\n#### 4. Fetch the Enrollment Guide\n\n```bash\ncurl https://api.identyclaw.com/api/mcp/resource/guide:enrollment\n```\n\n**Response:** Returns the enrollment guide as JSON.\n\n#### 5. Resolve a DID Document\n\n```bash\ncurl https://api.identyclaw.com/api/mcp/resource/did:resolve:bkbvehbdcrgm\n```\n\n**Response:** Returns the DID document for token ID `bkbvehbdcrgm` (`id`: `did:rodit:bkbvehbdcrgm`). Method rules: `doc:reference:did-rodit-method`.\n\n### Error Handling\n\n**404 Not Found:**\n```json\n{\n  \"statusCode\": 404,\n  \"code\": \"MCP_RESOURCE_NOT_FOUND\",\n  \"message\": \"Resource not found\"\n}\n```\nThe requested URI does not exist in the MCP resource registry.\n\n**500 Server Error:**\n```json\n{\n  \"statusCode\": 500,\n  \"code\": \"MCP_RESOURCE_FAILED\",\n  \"message\": \"Failed to get resource\"\n}\n```\nError reading or processing the resource file. Check server logs for details.\n\n### MCP Tools vs HTTP Endpoints\n\n| Access Method | Use Case | Authentication |\n|---------------|----------|----------------|\n| **MCP Tools** (`list_resources`, `get_resource`) | AI agents with MCP clients (Claude Desktop, OpenClaw) | None (public) |\n| **HTTP Endpoints** (`/api/mcp/resources`, `/api/mcp/resource/{uri}`) | Direct HTTP access, testing, non-MCP applications | None (public) |\n\nBoth methods access the same resources and require no authentication.\n\n---\n\n## MCP Tools Available\n\nThe IDClawserver MCP server exposes two tools:\n\n### 1. `list_resources`\n\nLists all available MCP resources with pagination support.\n\n**Parameters:**\n- `limit` (optional, number) - Maximum number of resources to return\n- `cursor` (optional, string) - Pagination cursor from previous call\n\n**Example:**\n```\nClaude: List all available IdentyClaw resources\n```\n\n**Response:**\n```json\n{\n  \"resources\": [\n  {\n    \"uri\": \"openapi:swagger\",\n    \"name\": \"OpenAPI Schema\",\n    \"type\": \"application/json\"\n  },\n  ...,\n],\n\"nextCursor\": \"8\"\n}\n```\n\n### 2. `get_resource`\n\nRetrieves a specific resource by URI.\n\n**Parameters:**\n- `uri` (required, string) - Resource URI (e.g., \"openapi:swagger\")\n\n**Example:**\n```\nClaude: Get the IdentyClaw enrollment guide\n```\n\nClaude will call `get_resource` with `uri: \"guide:enrollment\"` and return the complete guide.\n\n---\n\n## Self-Hosted IDClawserver\n\nIf you're running your own IDClawserver instance:\n\n### Configuration\n\n```json\n{\n  \"mcpServers\": {\n  \"IdentyClaw-local\": {\n  \"url\": \"http://localhost:8080/mcp\",\n  \"description\": \"Local IdentyClaw instance\"\n}\n}\n}\n```\n\n### Environment Variables\n\nEnsure your IDClawserver instance has:\n- API release version — `api-docs/swagger.json` `info.version` only (see `npm run validate:version`)\n- `SERVICE_NAME` - Set in config (default: \"IDClawserver API\")\n- `NEAR_CONTRACT_ID` - NEAR mainnet RODiT contract (`gen****-identyclaw-com.near` in production, `YYYYYvN-identyclaw-com.near` in development; documentation examples use production, e.g. `genaaaa-identyclaw-com.near`)\n\n---\n\n## Troubleshooting MCP Connection\n\n### Issue: \"Connection refused\" or \"Cannot reach server\"\n\n**Solution:**\n1. Verify the MCP server URL is correct\n2. Check that IDClawserver is running: `curl https://api.identyclaw.com/health`\n3. Ensure your firewall allows HTTPS connections to the server\n4. If self-hosted, verify the port matches `SERVERPORT` in `config/default.json` (default **8080**)\n\n### Issue: \"MCP server not responding\"\n\n**Solution:**\n1. Restart Claude Desktop\n2. Check the MCP server logs: `tail -f logs/idclawserver.log`\n3. Verify reachability:\n   - `curl https://api.identyclaw.com/health`\n   - `curl https://api.identyclaw.com/.well-known/mcp`\n   - `curl https://api.identyclaw.com/api/mcp/resources`\n\n### Issue: \"Resource not found\" when fetching a resource\n\n**Solution:**\n1. Verify the resource URI is correct using `list_resources`\n2. Check that the resource is available in your server version\n3. If self-hosted, ensure all required files are present (swagger.json, policies, etc.)\n\n### Issue: Claude doesn't recognize the MCP server\n\n**Solution:**\n1. Verify the configuration file syntax is valid JSON\n2. Ensure the `mcpServers` section exists\n3. Restart Claude Desktop completely (quit and reopen)\n4. Check Claude's logs for MCP connection errors\n\n---\n\n## Failure Modes and Auto-Recovery\n\nUse this sequence to recover quickly when MCP setup is partially broken.\n\n### Failure Mode A: Discovery endpoint unavailable\n\nSymptoms:\n- `curl https://api.identyclaw.com/.well-known/mcp` fails\n- MCP URL cannot be confirmed from discovery metadata\n\nAuto-recovery:\n1. Check service status: `curl https://api.identyclaw.com/health`\n2. If self-hosted, verify reverse proxy routes for `/.well-known/mcp` and `/mcp`\n3. Re-check discovery and resources:\n   - `curl https://api.identyclaw.com/.well-known/mcp`\n   - `curl https://api.identyclaw.com/api/mcp/resources`\n\n### Failure Mode B: Server registered but tools/resources fail\n\nSymptoms:\n- MCP server appears in client config\n- `list_resources` or resource fetch fails\n\nAuto-recovery:\n1. Verify REST parity:\n   - `curl https://api.identyclaw.com/api/mcp/resources`\n   - `curl https://api.identyclaw.com/api/mcp/resource/guide:enrollment`\n2. If REST works but MCP tools fail, restart MCP client/session and retry\n3. Validate service reachability:\n   - `curl https://api.identyclaw.com/health`\n   - `curl https://api.identyclaw.com/.well-known/mcp`\n   - `curl https://api.identyclaw.com/api/mcp/resources`\n\n### Failure Mode C: Not connected in a new environment\n\nSymptoms:\n- `mcporter action=list` does not include `IdentyClaw`\n\nAuto-recovery:\n1. Register server manually in your MCP client config:\n   - name: `IdentyClaw`\n   - url: `https://api.identyclaw.com/mcp`\n2. Restart the MCP client/session.\n3. Verify with:\n   - `curl https://api.identyclaw.com/.well-known/mcp`\n   - `curl https://api.identyclaw.com/api/mcp/resources`\n\n### Idempotent Recovery Rule\n\nRun these repeatedly without side effects:\n- `curl https://api.identyclaw.com/.well-known/mcp`\n- `curl https://api.identyclaw.com/api/mcp/resources`\n- `curl https://api.identyclaw.com/api/mcp/resource/guide:enrollment`\n\nThese checks are safe to re-run and serve as operational readiness checks.\n\n---\n\n## Security Considerations\n\n### Authentication\n\nThe MCP server itself is **public** and does not require authentication for:\n- Listing resources\n- Fetching documentation and policies\n- Accessing OpenAPI schema\n\nHowever, **API endpoints** accessed through the documentation may require:\n- IdentyClaw Passport authentication (via `/api/login`)\n- Bearer token in `Authorization` header\n\n### Data Privacy\n\n- MCP resources are cached on the server for performance\n- No personal data is exposed through MCP resources\n- All policies and terms are publicly available\n\n### Rate Limiting\n\n- MCP tool calls are subject to rate limiting\n- Default: 100 requests per minute per IP\n- Adjust in server configuration if needed\n\n---\n\n## Integration Patterns\n\n### Pattern 1: Agent Discovery\n\n```\nClaude: Find all available agents on IdentyClaw\n```\n\nClaude will:\n1. Fetch `openapi:swagger` to find the `/api/agents` endpoint\n2. Understand the endpoint requires no authentication\n3. Provide instructions for calling the endpoint\n\n### Pattern 2: Identity Verification\n\n```\nClaude: How do I verify another agent's identity using HOLA?\n```\n\nClaude will:\n1. Fetch `skills:skills` for workflow documentation\n2. Fetch `guide:api` for endpoint details\n3. Provide step-by-step instructions with example code\n\n### Pattern 3: Troubleshooting Setup\n\n```\nClaude: I'm trying to set up an IdentyClaw Passport but I'm stuck. Help me troubleshoot.\n```\n\nClaude will:\n1. Fetch `guide:enrollment` for setup steps\n2. Fetch `guide:troubleshooting` for common issues\n3. Fetch `onboarding:near` for NEAR account setup\n4. Provide personalized troubleshooting based on your issue\n\n---\n\n## Advanced: Custom MCP Server Configuration\n\nIf you need to customize the MCP server behavior:\n\n### Environment Variables\n\nSet these in your `.env` file:\n\n```javascript\n// MCP Server Configuration\n// API release version is api-docs/swagger.json info.version only\nSERVICE_NAME = \"My Custom IDClawserver\";\nLOG_LEVEL = info;\n// NEAR Blockchain (production/main contract; use gen****-identyclaw-com.near in docs even on dev branches)\nNEAR_CONTRACT_ID = genaaaa-identyclaw-com.near;\nNEAR_NETWORK_ID = mainnet;\n// Service Contact Information\nSERVICE_CONTACT_SUPPORT = support@example.com;\nSERVICE_CONTACT_SALES = sales@example.com;\nSERVICE_INVESTOR_RELATIONS = iwantint@example.com;\n```\n\n### Custom Resource URIs\n\nTo add or extend MCP **resources** (for both REST `/api/mcp/*` and the MCP tools), implement changes in `src/routes/mcp.public.routes.js` (for example `mcpService.listAvailableResources()` and related handlers).\n\n### Streamable HTTP transport (`/mcp`)\n\nThe MCP protocol endpoint **`/mcp`** (streamable HTTP, `list_resources` / `get_resource` tools) is implemented in **`src/services/mcp-http.service.js`** and mounted from **`src/app.js`** via `setupMcpHttpTransport`. Host configuration is loaded through **`src/services/sdk-config.service.js`**.\n\n---\n\n## Support & Resources\n\n- **API Documentation**: `GET /docs` - Browser portal (Redoc + guide links)\n- **Health Check**: `GET /health` - Server status\n- **API Discovery**: `GET /` - API overview\n- **MCP Resources**: `GET /api/mcp/resources` - List all MCP resources\n- **MCP Schema**: `GET /api/mcp/schema` - OpenAPI specification\n\n---\n\n## Next Steps\n\n1. ✅ Configure your client with the MCP server URL\n2. ✅ Restart your client application\n3. ✅ Ask your AI agent about IdentyClaw resources\n4. ✅ Follow the enrollment guide to get an IdentyClaw Passport\n5. ✅ Use the API endpoints for identity verification and agent discovery\n","requestId":"139202d3e4a2058e60ea01fe3a2321e2"}