|
| 1 | +# MCP Server Setup |
| 2 | + |
| 3 | +> This is an **advanced** guide for those who want to integrate AI Agents with the Cheqd Network to create DIDs and Issue Verifiable Credentials. |
| 4 | +
|
| 5 | +## Overview |
| 6 | + |
| 7 | +The **Cheqd MCP Server** is a specialised implementation of the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) that integrates with the **cheqd** network to provide secure decentralised identity management capabilities for AI applications. Built on the powerful combination of MCP's standardised context protocol and **cheqd**'s robust identity infrastructure, this server enables AI agents to perform sophisticated identity operations while maintaining security, privacy, and verifiability. |
| 8 | + |
| 9 | +Our MCP server is designed as a modular toolkit that can be easily integrated with existing AI workflows, particularly through Claude Desktop, Cursor, and other MCP-compatible client applications.  |
| 10 | + |
| 11 | +### Benefits of using MCP with cheqd |
| 12 | + |
| 13 | +* **Enhanced AI Trust and Verification**: Enable AI agents to create, resolve, and verify decentralised identities, establishing a foundation of trust for AI interactions. |
| 14 | +* **Verifiable Credential Management**: Simplify the issuance, verification, and management of verifiable credentials through standardised tools. |
| 15 | +* **Decentralised Identity Operations**: Leverage cheqd's blockchain infrastructure for creating and managing DIDs with cryptographic security. |
| 16 | +* **Standardised AI Context**: Utilise the Model Context Protocol to provide structured and verifiable context for AI interactions. |
| 17 | +* **Human-in-the-loop Security**: MCP's approval-based tool execution model ensures humans maintain oversight of sensitive identity operations. |
| 18 | +* **Interoperable Integration**: Seamlessly connect with existing identity ecosystems through the cheqd network and Credo Toolkit. |
| 19 | + |
| 20 | +### Integration with Credo Toolkit |
| 21 | + |
| 22 | +The server includes deep integration with the Credo Toolkit ([`@cheqd/mcp-toolkit-credo`](https://www.npmjs.com/package/@cheqd/mcp-toolkit-credo)), which provides a comprehensive set of tools for interacting with the cheqd network through the OpenWalletFoundation's Credo-TS framework. This integration enables: |
| 23 | + |
| 24 | +* **DID Management**: Create, update, resolve, and deactivate DIDs on the cheqd network. |
| 25 | +* **Resource Operations**: Create and resolve DID-linked resources. |
| 26 | +* **Schema Management**: Define and retrieve credential schemas for standardised credential formats. |
| 27 | +* **Connection Management**: Establish secure DIDComm connections between identity holders and verifiers. |
| 28 | +* **Credential Issuance**: Generate and issue verifiable credentials with cryptographic proofs. |
| 29 | +* **Verification Protocols**: Implement zero-knowledge proof verification for enhanced privacy. |
| 30 | + |
| 31 | +The Credo Toolkit abstracts the complexity of these operations, presenting them as simple, well-documented MCP tools that can be invoked by AI agents with appropriate permissions. By leveraging the Credo Toolkit integration, the MCP server provides comprehensive tools for managing the full lifecycle of decentralised identifiers (DIDs) and verifiable credentials on the cheqd network. |
| 32 | + |
| 33 | +### Target Use Cases and Scenarios |
| 34 | + |
| 35 | +The Cheqd MCP Server is particularly well-suited for scenarios requiring trusted AI interactions with verifiable identity information: |
| 36 | + |
| 37 | +* **AI-Assisted Identity Verification**: Enable AI agents to verify user identities through cryptographically secured credentials. |
| 38 | +* **Credential Issuance Workflows**: Streamline the creation and issuance of verifiable credentials through AI-guided processes. |
| 39 | +* **Trusted Data Exchange**: Facilitate secure sharing of verified data between organisations using AI intermediaries. |
| 40 | +* **Identity-Aware AI Systems**: Build AI applications that respect privacy and understand the provenance of identity information. |
| 41 | +* **Cross-Domain Verification**: Enable verification of credentials across different systems and networks through the cheqd infrastructure. |
| 42 | +* **Self-Sovereign Identity Management**: Support user control over identity information while enabling AI assistance for complex operations. |
| 43 | + |
| 44 | +## Getting Started |
| 45 | + |
| 46 | +### Prerequisites |
| 47 | + |
| 48 | +* An MCP Compatible Desktop based **AI Agent**. We have tested with [Claude Desktop](https://claude.ai/download). |
| 49 | +* **Node.js 20 or higher** (if running using npx). |
| 50 | +* **Docker Desktop** (if running using docker). This is preferred when running the ACA-Py demo. |
| 51 | +* **Working understanding of cheqd network**: Understanding of DID operations and verifiable credentials |
| 52 | + |
| 53 | +### Configuration |
| 54 | + |
| 55 | +The Cheqd MCP Server is configurable through environment variables: |
| 56 | + |
| 57 | +#### Server Configuration Options |
| 58 | + |
| 59 | +<table><thead><tr><th width="291.85546875">Variable</th><th width="314.66796875">Description</th><th>Default</th></tr></thead><tbody><tr><td><code>TOOLS</code></td><td>Comma-separated list of tools to enable</td><td>"credo"</td></tr></tbody></table> |
| 60 | + |
| 61 | +#### Credo Tool Configuration Options |
| 62 | + |
| 63 | +<table><thead><tr><th width="296.36328125">Variable</th><th width="314.140625">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>CREDO_CHEQD_TESTNET_MNEMONIC</code></td><td>Mnemonic for cheqd testnet wallet</td><td>Yes</td></tr><tr><td><code>CREDO_PORT</code></td><td>Port for the Credo agent</td><td>No</td></tr><tr><td><code>CREDO_NAME</code></td><td>Name for the Credo agent</td><td>No</td></tr><tr><td><code>CREDO_ENDPOINT</code></td><td>Public endpoint for DIDComm connections</td><td>No</td></tr></tbody></table> |
| 64 | + |
| 65 | +### Setup |
| 66 | + |
| 67 | +#### 1. Get the code |
| 68 | + |
| 69 | +Get the `docker-compose.yaml` specially designed for Claude:  |
| 70 | + |
| 71 | +```bash |
| 72 | +# Clone the repository |
| 73 | +git clone https://github.com/cheqd/mcp-toolkit.git |
| 74 | +cd mcp-toolkit |
| 75 | +``` |
| 76 | + |
| 77 | +#### 2. Create Configuration File |
| 78 | + |
| 79 | +Update your local `env.example` file with the required environment variables: |
| 80 | + |
| 81 | +{% code title="./env.example" %} |
| 82 | +```env |
| 83 | +TOOLS="credo" # Required tool configuration |
| 84 | +CREDO_PORT="3000" # Port for the Credo agent |
| 85 | +CREDO_NAME="faber" # Name of the Credo agent |
| 86 | +CREDO_ENDPOINT="http://faber:3000" # Public endpoint connections |
| 87 | +CREDO_CHEQD_TESTNET_MNEMONIC="your-testnet-mnemonic" # Required for cheqd network access |
| 88 | +``` |
| 89 | +{% endcode %} |
| 90 | + |
| 91 | +Replace `your-testnet-mnemonic` with a valid mnemonic for the cheqd testnet. You can generate one using the cheqd CLI or get one from the cheqd faucet. |
| 92 | + |
| 93 | +#### 3. Update Claude Config |
| 94 | + |
| 95 | +Add the following configuration to your claude\_desktop\_config.json or .cursor/mcp.json |
| 96 | + |
| 97 | +```json |
| 98 | +{ |
| 99 | + "mcpServers": { |
| 100 | + "cheqd": { |
| 101 | + "command": "docker", |
| 102 | + "args": [ |
| 103 | + "compose", |
| 104 | + "-f", |
| 105 | + "/path/to/repo/mcp-toolkit/docker/docker-compose.yml", |
| 106 | + "run", |
| 107 | + "--rm", |
| 108 | + "-p", |
| 109 | + "3000:3000", |
| 110 | + "-T", |
| 111 | + "mcp-server" |
| 112 | + ] |
| 113 | + } |
| 114 | + } |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +#### 4. Restart Claude Desktop |
| 119 | + |
| 120 | +When successfully started, the number of tools available to Claude Desktop will increase. |
| 121 | + |
| 122 | +<figure><img src="../../.gitbook/assets/Screenshot 2025-03-28 at 16.46.59.png" alt=""><figcaption></figcaption></figure> |
| 123 | + |
| 124 | +{% hint style="warning" %} |
| 125 | +There may be a error on top right corner, but it can be safely ignored. It is because of port binding, as Claude creates two processes for each MCP Server. |
| 126 | +{% endhint %} |
| 127 | + |
| 128 | +### Connection to cheqd network |
| 129 | + |
| 130 | +The server automatically connects to the cheqd testnet using the provided mnemonic. This connection is used for all DID operations and credential management. |
| 131 | + |
| 132 | +#### Verifying Network Connection |
| 133 | + |
| 134 | +To verify the connection to the cheqd network, you can use the server to create and resolve a DID. You can ask the following to the AI Agent: |
| 135 | + |
| 136 | +> "Can you create a DID on the cheqd network?" |
| 137 | +
|
| 138 | +If configured correctly, the server will create a new DID and then display its complete DID document, confirming proper connection to the cheqd network. |
| 139 | + |
| 140 | +## Next Steps |
| 141 | + |
| 142 | +Now that you have the Cheqd MCP Server running, you can: |
| 143 | + |
| 144 | +* Explore the available tools for DID management and credential operations |
| 145 | +* Create your first verifiable credential using the provided tools |
| 146 | +* Set up a complete identity verification workflow |
0 commit comments