ResilientDB

You run a dedicated MCP server that bridges Claude-like AI agents with ResilientDB. It exposes two interfaces: a GraphQL endpoint for blockchain asset transactions and an HTTP REST API for simple key-value storage. With this server you can create accounts, read and post asset transactions, and perform fast KV operations, enabling seamless interaction between AI workflows and the ResilientDB backend.

How to use

Install and run the MCP server, then connect your MCP client to the two exposed endpoints. Use the GraphQL interface on port 8000 for asset transactions and the HTTP REST API on port 18000 for key-value storage. The server routes requests automatically: asset-related actions go to GraphQL, while key-value operations use the Crow REST API.

How to install

Prerequisites you need before installing:

• Python 3.11 or higher
• A running ResilientDB instance
• Access to the ResilientDB GraphQL endpoint
• Optional: ResContract CLI if you plan to work with smart contracts (currently disabled in midterm)

Local installation steps you can follow:

# Step 1: Clone the MCP server repository
git clone https://github.com/rahulkanagaraj786/ResilientDB-MCP.git
cd ResilientDB-MCP

# Step 2: Install dependencies
pip install -r requirements.txt

# Step 3: Copy and edit environment configuration
cp .env.example .env
# Edit .env with your ResilientDB configuration

# Step 4: Run the MCP server locally (example using Python)
python server.py

Configuration and runtime options

Environment variables you should configure in your environment file (.env):

• RESILIENTDB_GRAPHQL_URL: GraphQL endpoint URL (port 8000 for asset transactions)
• RESILIENTDB_HTTP_URL: HTTP/Crow server URL (port 18000 for KV operations)
• RESILIENTDB_API_KEY: Optional API key for authentication
• RESILIENTDB_AUTH_TOKEN: Optional auth token
• REQUEST_TIMEOUT: Request timeout in seconds (default 30)
• TRANSACTION_POLL_INTERVAL: Polling interval for transactions (default 1.0)
• MAX_POLL_ATTEMPTS: Maximum polling attempts (default 30)

Running with Docker

If you prefer to run the MCP server in Docker, use the following commands to build and run the container.

# Build the Docker image
docker build -t mcp/resilientdb -f Dockerfile .

# Run the container
docker run -i --rm mcp/resilientdb

Available tools and capabilities

The MCP server provides a set of tools to interact with ResilientDB:

• createAccount: Create a new account in ResilientDB (optional accountId can be provided)
• getTransaction: Retrieve asset transaction details by ID (GraphQL port 8000)
• postTransaction: Post a new asset transaction to the blockchain (requires PrepareAsset format with crypto keys)
• updateTransaction: Update an existing transaction (subject to blockchain immutability)
• get: Retrieve a value by key via HTTP REST API (Crow server on port 18000)
• set: Store a key-value pair via HTTP REST API (Crow server on port 18000)

Troubleshooting

Common issues and steps to resolve them include checking that the GraphQL endpoint is reachable, ensuring the Crow server is running on port 18000, and validating environment configurations. If you encounter connection errors, verify the URLs in RESILIENTDB_GRAPHQL_URL and RESILIENTDB_HTTP_URL, confirm network access to ports 8000 and 18000, and test endpoints with curl commands adapted to your environment.

Security considerations

Protect your API key and auth tokens. If you expose the MCP server publicly, enforce network restrictions and use strong credentials. Only enable the features you need (GraphQL asset transactions vs KV storage) and monitor access patterns for unusual activity.

Available tools

createAccount

Create a new account in ResilientDB. You may optionally provide an accountId; if omitted, the server will generate one.

getTransaction

Retrieve asset transaction details by transaction ID using the GraphQL API on port 8000.

postTransaction

Post a new asset transaction to the blockchain via GraphQL. Requires data in PrepareAsset format with cryptographic keys and signatures.

updateTransaction

Update an existing transaction. Note that blockchain transactions are typically immutable, so updates may be limited.

get

Retrieve a value by key using the HTTP REST API (Crow server on port 18000).

set

Store a key-value pair using the HTTP REST API (Crow server on port 18000).