Linera Counter Server

This demo showcases an MCP (Model Context Protocol) server that connects to a counter application running on the Linera blockchain via GraphQL. The MCP server enables Claude to interact with the on-chain counter through natural language commands.

Architecture Overview

• Linera Counter Application: A counter application deployed on Linera that exposes GraphQL endpoints
• Apollo MCP Server: Acts as a bridge between Claude and the Linera GraphQL API
• Claude Desktop: MCP client that can query and mutate the counter through natural language

Prerequisites

1. Linera CLI: Ensure you have the linera binary installed and available in your PATH

2. Rust: Required to build and run the Apollo MCP server

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

3. Claude Desktop: Install Claude Desktop app to connect to the MCP server

Setup Instructions

Step 1: Install Apollo MCP Server

1. Clone the Apollo MCP Server repository:

   git clone https://github.com/apollographql/apollo-mcp-server.git
   cd apollo-mcp-server
   

2. Build the MCP server:

   cargo build --release
   

Step 2: Deploy the Counter Application on Linera

1. Start your Linera validator and ensure you have a default chain configured:

   linera wallet show
   

2. Deploy the counter application using the linera CLI with an initial value:

   linera project publish-and-create examples/counter --json-argument "0"
   

   This command will:

   • Build the counter application bytecode
   • Publish it to your chain
   • Create an application instance initialized with counter value 0
   • Return the application ID (note this for the next step)

3. Start the Linera service with GraphQL enabled:

   linera service --port 8080
   

   This starts the Linera node service with GraphQL endpoint at http://localhost:8080

Step 3: Launch the Apollo MCP Server

1. From the apollo-mcp-server directory, run the MCP server with your specific chain ID and application ID:

   cargo run -- \
     --schema ../counter.graphql \
     --endpoint http://localhost:8080/chains/<YOUR_CHAIN_ID>/applications/<YOUR_APPLICATION_ID> \
     --allow-mutations all \
     --introspection \
     --http-address 127.0.0.1
   

   Replace:

   • <YOUR_CHAIN_ID> with your actual chain ID (from linera wallet show)
   • <YOUR_APPLICATION_ID> with the application ID returned from Step 2

   Example:

   cargo run -- \
     --schema ../counter.graphql \
     --endpoint http://localhost:8080/chains/e9baa1f0e0a3b8c61b13a61a106e446bcffaea77fa13a8d2164b681c37aa34e1/applications/2b1a0df8868206a4b7d6c2fdda911e4355d6c0115b896d4947ef8e535ee3c6b8 \
     --allow-mutations all \
     --introspection \
     --http-address 127.0.0.1
   

   The MCP server will:

   • Connect to the Linera GraphQL endpoint
   • Introspect the counter application schema
   • Expose counter operations as MCP tools
   • Listen for MCP client connections on stdio

Step 4: Connect Claude Desktop

1. Configure Claude Desktop to connect to the MCP server by adding this to your Claude Desktop configuration:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "linera-counter": {
         "command": "cargo",
         "args": [
           "run",
           "--manifest-path",
           "/path/to/apollo-mcp-server/Cargo.toml",
           "--",
           "--schema",
           "/path/to/claude-demo/counter.graphql",
           "--endpoint",
           "http://localhost:8080/chains/<YOUR_CHAIN_ID>/applications/<YOUR_APPLICATION_ID>",
           "--allow-mutations",
           "all",
           "--introspection",
           "--http-address",
           "127.0.0.1"
         ],
         "env": {}
       }
     }
   }
   

   Note: Replace /path/to/apollo-mcp-server/ with the actual path to where you cloned the Apollo MCP Server repository, and replace the chain/application IDs with your actual values.

2. Restart Claude Desktop to load the MCP server configuration.

Available Tools

The MCP server automatically discovers and exposes the following tools based on the counter GraphQL schema:

Query Tools

• value: Query the current counter value
  • Returns the current integer value of the counter

Mutation Tools

• increment: Increment the counter by a specified value
  • Parameters: value (Int!) - The amount to increment by
  • Returns: Array of integers representing the operation result

Example Claude Session

Once everything is set up, you can interact with the Linera counter through Claude:

---

You: "What's the current value of the counter?"

Claude: I'll check the current counter value for you.

[Uses the value query tool]

The current counter value is 0.

---

You: "Increment the counter by 5"

Claude: I'll increment the counter by 5 for you.

[Uses the increment mutation tool with value: 5]

Successfully incremented the counter by 5. The operation completed and returned [5].

---

You: "What's the counter value now?"

Claude: Let me check the updated counter value.

[Uses the value query tool]

The counter value is now 5.

---

You: "Add 10 more to the counter"

Claude: I'll add 10 to the counter.

[Uses the increment mutation tool with value: 10]

Successfully incremented the counter by 10. The operation returned [15], and the counter value is now 15.

---

You: "Can you increment it by 3 and then tell me the new value?"

Claude: I'll increment the counter by 3 and then check the new value for you.

[Uses the increment mutation tool with value: 3]

[Uses the value query tool]

I've successfully incremented the counter by 3. The counter value is now 18.

---

Troubleshooting

Common Issues

1. Connection Refused: Ensure the Linera service is running on the correct port

   linera service --port 8080
   

2. Invalid Chain/Application ID: Use linera wallet show to verify your chain ID and ensure you're using the correct application ID from deployment

3. MCP Server Not Found: Check that the file paths in the Claude Desktop configuration are correct and that Rust/Cargo are properly installed

4. GraphQL Schema Errors: Ensure the counter application is deployed and the Linera service can access it

Debugging Commands

Check if the Linera service is accessible:

curl http://localhost:8080/

Query the counter directly via GraphQL:

curl -X POST http://localhost:8080/chains/<CHAIN_ID>/applications/<APP_ID> \
  -H "Content-Type: application/json" \
  -d '{"query": "{ value }"}'

List your deployed applications:

linera wallet show

Test the MCP server connection:

cd apollo-mcp-server
cargo run -- \
  --endpoint http://localhost:8080/chains/<YOUR_CHAIN_ID>/applications/<YOUR_APPLICATION_ID> \
  --allow-mutations all \
  --introspection \
  --http-address 127.0.0.1

Next Steps

• Explore other Linera example applications that could be exposed via MCP
• Try building custom applications with more complex GraphQL schemas
• Experiment with different MCP client integrations beyond Claude Desktop
• Build multi-chain applications that can be federated through the MCP server

For more information about Linera development, see the Linera Documentation.

For more about Apollo MCP Server, see the Apollo MCP Server repository.