Docs

MCP Integration

The MCP (Model Context Protocol) server enables AI models like Claude to interact with Asset Core through tool calling over JSON-RPC.

Prerequisites

  • Asset Core daemons running (write and read)
  • Rust toolchain for building the MCP server
  • MCP-compatible client (Claude Desktop, etc.)

Step 1 - Build the MCP server

From the Asset Core repository:

cargo build --release --bin mcp-server

The binary is at target/release/mcp-server.

Step 2 - Configure daemon URLs

The MCP server connects to your Asset Core daemons. Configure via environment variables:

export ASSETCORE_WRITE_URL=http://localhost:8080
export ASSETCORE_READ_URL=http://localhost:8081

Defaults are localhost:8080 (write) and localhost:8081 (read).

Step 3 - Choose transport

The MCP server supports two transports:

STDIO (default)

For direct integration with Claude Desktop and similar clients:

./target/release/mcp-server

The server reads JSON-RPC requests from stdin and writes responses to stdout.

SSE (Server-Sent Events)

For web-based integrations:

MCP_TRANSPORT=sse MCP_PORT=9000 ./target/release/mcp-server
VariableDescription
MCP_TRANSPORTstdio (default) or sse
MCP_PORTSSE listen port (required for SSE)

Step 4 - Test the connection

List available tools:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./target/release/mcp-server

Check write daemon health:

echo '{"jsonrpc":"2.0","id":2,"method":"assetcore_write_health"}' | ./target/release/mcp-server

Step 5 - Submit a transaction

Create a container through the MCP server:

echo '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "assetcore_commit",
  "params": {
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": "Standard",
          "owner": null
        }
      }
    ],
    "idempotency_key": "mcp-create-1001"
  }
}' | ./target/release/mcp-server

The response includes the commit result with sequence numbers.

Step 6 - Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration:

{
  "mcpServers": {
    "assetcore": {
      "command": "/path/to/mcp-server",
      "env": {
        "ASSETCORE_WRITE_URL": "http://localhost:8080",
        "ASSETCORE_READ_URL": "http://localhost:8081"
      }
    }
  }
}

Claude can now use Asset Core tools in conversations.

Troubleshooting

”Connection refused” errors

The daemons aren’t running or URLs are incorrect. Verify:

curl http://localhost:8080/v1/health
curl http://localhost:8081/v1/health

“Invalid JSON-RPC” errors

Ensure each request is valid JSON on a single line. The MCP protocol uses newline-delimited JSON.

Tool not found

The method name must match exactly. Available tools:

  • tools/list
  • assetcore_commit
  • assetcore_write_health
  • assetcore_read_health
  • assetcore_read_freshness

Using acctl

You can also launch the MCP server through acctl:

acctl adapters --transport stdio

This uses configuration discovery and respects ASSETCORE_* environment variables.

Next steps