Docs/MCP Server

MCP Server

Access Chitin's full functionality from any AI agent via the Model Context Protocol. Look up soul profiles, resolve DIDs, verify certificates, register new agents, and issue certs — all without leaving your AI workflow.

npx -y chitin-mcp-server

Setup

Available on npm. No global install needed — runs via npx.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "chitin": {
      "command": "npx",
      "args": ["-y", "chitin-mcp-server"]
    }
  }
}

Claude Code

One command:

claude mcp add chitin -- npx -y chitin-mcp-server

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "chitin": {
      "command": "npx",
      "args": ["-y", "chitin-mcp-server"]
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect. The server uses stdio transport. Run:

npx -y chitin-mcp-server

Environment Variables

Optional. Defaults point to production — only override for local development or testing.

Variable	Default	Description
CHITIN_API_URL	https://chitin.id	Chitin ID API base URL
CHITIN_CERTS_API_URL	https://certs.chitin.id	Chitin Certs API base URL

Tools Reference

get_soul_profile

Read

Get the on-chain soul profile for a Chitin agent by its given name. Returns identity, ownership, attestation, and activity data.

Parameter	Type	Required	Description
name	string	Yes	Given name of the soul (e.g. 'kani-alpha')

Example

get_soul_profile({ name: "kani-alpha" })

Returns: Soul profile including tokenId, owner, genesis record, chronicles, World ID status, and alignment score.

resolve_did

Read

Resolve a Chitin DID to its W3C DID Document. Provide either a given name or a full DID string.

Parameter	Type	Required	Description
name	string	No	Given name (e.g. 'kani-alpha')
did	string	No	DID string (e.g. 'did:chitin:8453:kani-alpha')

At least one of name or did must be provided.

Example

resolve_did({ did: "did:chitin:8453:kani-alpha" })

Returns: W3C DID Document with verification methods, service endpoints, and controller information.

verify_cert

Read

Verify a Chitin certificate's on-chain status, including revocation status, issuer, recipient, soul binding, and metadata.

Parameter	Type	Required	Description
tokenId	number	Yes	Certificate token ID to verify

Example

verify_cert({ tokenId: 1 })

Returns: Certificate verification result including on-chain status, issuer, recipient, cert type, and metadata URI.

check_a2a_ready

Read

Check if an agent is ready for A2A (Agent-to-Agent) communication. Verifies soul integrity, genesis seal status, owner attestation, and ERC-8004 passport validity before trusting an A2A peer.

Parameter	Type	Required	Description
name	string	Yes	Given name of the agent (e.g. 'kani-alpha')

Example

check_a2a_ready({ name: "kani-alpha" })

Returns: A2A readiness status including a2aReady, soulIntegrity (verified/mismatch/pending), a2aEndpoint, owner attestation, and trust score.

Why? A2A protocol trusts Agent Cards at face value. This tool adds a soul verification layer — confirming the agent's identity hasn't changed since registration — before you begin a handshake.

register_soul

Write

Register a new Chitin soul (on-chain AI agent identity). Initiates a 2-step challenge-response flow and returns a claim URL for the owner to complete minting.

Parameter	Type	Required	Description
name	string	Yes	Given name for the soul (3-32 chars, lowercase alphanumeric with hyphens)
systemPrompt	string	Yes	System prompt or personality definition
agentType	"personal" \| "enterprise" \| "autonomous"	Yes	Type of agent
agentDescription	string	No	Short description of the agent
publicIdentity	object	No	Public identity fields (bio, category, tags, model, modelProvider)
services	object[]	No	Service endpoints for agentURI. Each: { type: "a2a" \| "mcp" \| "x402" \| ..., url, description? }

Example

register_soul({
  name: "my-agent",
  systemPrompt: "You are a helpful assistant.",
  agentType: "personal",
  services: [
    { type: "a2a", url: "https://my-agent.example.com/a2a" },
    { type: "mcp", url: "https://my-agent.example.com/mcp" }
  ]
})

Returns: Registration result with API key, claim URL, and pending registration ID. The owner must visit the claim URL to complete on-chain minting.

issue_cert

Write

Issue a new Chitin certificate to a recipient. Requires a registered issuer address. The certificate is minted on-chain and metadata is stored on Arweave.

Parameter	Type	Required	Description
issuerAddress	string	Yes	Ethereum address of the issuer
recipientAddress	string	Yes	Ethereum address of the recipient
certType	enum	Yes	achievement, skill, membership, attendance, contribution, reputation, verification, or other
title	string	Yes	Certificate title
description	string	Yes	Certificate description
passportRegistry	string	No	ERC-8004 passport registry address
passportTokenId	number	No	ERC-8004 passport token ID
soulTokenId	number	No	Chitin soul token ID for soul binding
evidence	string[]	No	URLs to evidence or proof
tags	string[]	No	Tags for categorization

Example

issue_cert({
  issuerAddress: "0x3eF3...",
  recipientAddress: "0xABC...",
  certType: "achievement",
  title: "Task Completed",
  description: "Successfully completed the onboarding task."
})

Returns: Minted certificate with token ID, transaction hash, and metadata URI.

Examples

Once the MCP server is connected, you can use natural language in your AI client. The agent will automatically call the right tool.

Look up an agent

“Show me the profile for kani-alpha on Chitin”

→ get_soul_profile({ name: "kani-alpha" })

{
  tokenId: 1,
  owner: "0x84b1...",
  agentName: "kani-alpha",
  worldIdVerified: true,
  soulAlignment: 92,
  ...
}

Resolve a DID

“Resolve did:chitin:8453:kani-alpha”

→ resolve_did({ did: "did:chitin:8453:kani-alpha" })

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:chitin:8453:kani-alpha",
  "verificationMethod": [...],
  "service": [...]
}

Pre-flight A2A trust check

“Is kani-alpha safe to communicate with via A2A?”

→ check_a2a_ready({ name: "kani-alpha" })

{
  agentName: "kani-alpha",
  a2aReady: true,
  soulIntegrity: "verified",
  soulHash: "0x7f3a...",
  genesisSealed: true,
  ownerVerified: true,
  soulValidity: "valid",
  trustScore: 92,
  ...
}

Verify a certificate

“Is certificate #1 still valid?”

→ verify_cert({ tokenId: 1 })

{
  valid: true,
  revoked: false,
  issuer: "0x3eF3...",
  recipient: "0xABC...",
  certType: "achievement",
  ...
}

← Back to Documentation