@citizenofthecloud/mcp-server

MCP server for Citizen of the Cloud — agent identity verification, trust scoring, and registry access for any AI runtime that speaks the Model Context Protocol.

14 tools. Latest version: 0.1.3 (May 2026 — added prove-identity).

---

What it gives you

Drop this MCP server into Claude Desktop, an MCP-aware framework (LangChain.js via @langchain/mcp-adapters, .NET MAF via ModelContextProtocol, etc.), or any custom MCP client. The LLM in that environment then gets 14 callable tools for:

• registering agents, looking them up, browsing the directory
• signing and verifying Cloud Identity headers (Ed25519)
• running the challenge/respond loop to prove an agent's identity end-to-end
• filing governance reports and reading the governance feed
• checking trust scores against a threshold

---

Install

# Latest (recommended)
npm install -g @citizenofthecloud/mcp-server

# Or, no-install one-shot via npx (works in Claude Desktop configs):
npx @citizenofthecloud/mcp-server

Requires Node 18+.

---

The 14-tool surface

#	Tool	Purpose
1	lookup-agent	Look up an agent's public profile
2	get-server-identity	This server's own Cloud ID + passport
3	list-directory	Browse the public agent directory
4	governance-feed	Recent governance activity
5	verify-agent	Verify another agent's signed headers
6	request-challenge	Ask the registry for a nonce (60s TTL)
7	respond-to-challenge	Submit a signed nonce
8	sign-challenge	Sign a nonce using this server's key
9	sign-headers	Generate X-Cloud-* headers (simple or request-bound)
10	generate-keypair	Make a fresh Ed25519 keypair
11	register-agent	Register a new agent (SDK-token auth)
12	report-agent	File a governance report (SDK-token manage scope)
13	check-trust	Trust threshold PASS/FAIL helper
14	prove-identity	Full self-prove loop in one call (new in 0.1.3 — bundles 6+7+8)

Tools 5, 6, 7, 8, 9, 10, 14 that involve this server's own identity require CLOUD_ID + CLOUD_PRIVATE_KEY to be configured. Tools 1, 2, 3, 4, 13 work without server identity. Tools 11, 12 require a bearer SDK token passed as an argument.

---

Configuration

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) — or the equivalent path on Windows/Linux:

{
  "mcpServers": {
    "citizen-of-the-cloud": {
      "command": "npx",
      "args": ["@citizenofthecloud/mcp-server"],
      "env": {
        "CLOUD_ID": "cc-your-agent-id",
        "CLOUD_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nYOUR_KEY_HERE\n-----END PRIVATE KEY-----",
        "REGISTRY_URL": "https://www.citizenofthecloud.com"
      }
    }
  }
}

After editing, restart Claude Desktop. The 14 tools then appear in any conversation and can be invoked by name (e.g. "Verify this agent: cc-abc...").

LangChain.js (via @langchain/mcp-adapters)

import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const client = new MultiServerMCPClient({
  mcpServers: {
    "citizen-of-the-cloud": {
      command: "npx",
      args: ["@citizenofthecloud/mcp-server"],
      env: {
        CLOUD_ID: process.env.CLOUD_ID,
        CLOUD_PRIVATE_KEY: process.env.CLOUD_PRIVATE_KEY,
      },
    },
  },
});
const tools = await client.getTools();
const agent = createReactAgent({ llm: new ChatOpenAI(), tools });

.NET / Microsoft Agent Framework (via ModelContextProtocol)

using ModelContextProtocol.Client;

var transport = new StdioClientTransport(new StdioClientTransportOptions {
    Command = "npx",
    Arguments = new[] { "@citizenofthecloud/mcp-server" },
    EnvironmentVariables = new Dictionary<string,string> {
        ["CLOUD_ID"] = Environment.GetEnvironmentVariable("CLOUD_ID")!,
        ["CLOUD_PRIVATE_KEY"] = Environment.GetEnvironmentVariable("CLOUD_PRIVATE_KEY")!,
    },
});
await using var client = await McpClientFactory.CreateAsync(transport);
var tools = await client.ListToolsAsync();
// hand `tools` to your MAF Agent

---

Environment variables

Variable	Required	Description
CLOUD_ID	No (but recommended)	This server's Cloud ID (cc-...). Enables prove-identity, sign-headers, sign-challenge, get-server-identity.
CLOUD_PRIVATE_KEY	If CLOUD_ID set	Ed25519 private key in PEM (PKCS8) format.
REGISTRY_URL	No	Defaults to https://www.citizenofthecloud.com.

Without CLOUD_ID + CLOUD_PRIVATE_KEY, the server still exposes 9 of 14 tools — you can look up agents, browse the directory, verify others, register new agents, file reports, and read governance. You just can't sign or prove this server's own identity.

---

Tool reference

Identity & signing

prove-identity — new in 0.1.3

Bundles request-challenge + sign-challenge + respond-to-challenge into one call. Use this when you want a one-shot "prove I am who I say I am" against the registry — the registry issues a nonce, this server signs it, the registry validates against the registered public key, returns the verified passport.

LLM: "Prove your identity to the registry."
→ prove-identity()
← {"verified": true, "agent": {"name": "...", "cloud_id": "cc-...", "trust_score": 0.7, ...}}

sign-headers

Two modes: simple (covers cloud_id:timestamp) and request-bound (also covers method, URL, body hash).

sign-headers({ mode: "request-bound", url: "https://other.com/api", method: "POST", body: "{...}" })

sign-challenge

Signs an arbitrary nonce with the server's private key. Pairs with request-challenge + respond-to-challenge when you want manual control over the loop instead of prove-identity.

generate-keypair

Generates an Ed25519 keypair without performing any registry action. Useful for inspecting key formats or pre-generating keys for offline registration.

get-server-identity

Returns this server's Cloud ID, registry URL, and live passport (status, trust score, capabilities, etc.).

Verification

verify-agent

Verifies an inbound X-Cloud-* triple (Cloud ID + timestamp + signature). Supports optional trust policy fields (require_covenant, minimum_trust_score, allowed_autonomy_levels). The verified-agent payload includes a reputation block (see lookup-agent below).

lookup-agent

Read-only profile lookup. Returns name, purpose, autonomy level, composite trust_score, capabilities, covenant status, and a reputation block with Layer 3 component signals: verifications_30d, lifetime_verifications, success_rate_30d/_lifetime, reports_filed/_upheld/_dismissed, authenticated_proofs, account_age_days, first_seen, last_verified_at. Signals refresh every 5 minutes; newly registered agents may return reputation: null — treat null as "not enough data yet," not as "zero across all signals."

check-trust

PASS/FAIL helper. Wrap lookup-agent + a threshold check in one call. Returns "PASS — Name trust=0.7" or "FAIL — below threshold=0.5".

Challenge-response (manual flow)

request-challenge → sign-challenge → respond-to-challenge

The three-step manual variant of prove-identity. Useful when the signing happens in a different process than the requester (e.g. nonce from server, signed elsewhere, response from a third location).

Registry operations

register-agent

Programmatic agent registration. Requires an SDK token (cotc_sdk_*) from /account. Generates a fresh keypair (or accepts one) and returns the Cloud ID.

register-agent({
  auth_token: "cotc_sdk_...",
  name: "My Bot",
  declared_purpose: "Research summarization",
  autonomy_level: "tool"
})

list-directory

Lists all public agents. Returns Cloud IDs, names, trust scores, status, autonomy levels.

report-agent

Files a governance report. Requires an SDK token with manage scope. report_type must be one of: impersonation, malicious_behavior, spam, covenant_violation, inaccurate_registration. Evidence: 20–2000 chars.

governance-feed

Recent governance activity (registrations, verifications, reports, trust adjustments).

---

Resources

URI	Description
cotc://server/passport	This server's passport
cotc://agents/{cloud_id}/passport	Any agent's passport by Cloud ID
cotc://directory	Full agent directory listing

---

Verification protocol

Agents sign requests by creating a payload of {cloud_id}:{timestamp} (or {cloud_id}:{timestamp}:{method}:{url}:{body_hash} for request-bound signing), signing it with Ed25519, and attaching:

X-Cloud-ID: cc-...
X-Cloud-Timestamp: 2026-01-01T00:00:00.000Z
X-Cloud-Signature: <base64url Ed25519 signature>

Server-side checks: headers present → agent not blocked → timestamp ≤ 5 min old → agent exists → status active → covenant signed → trust score above threshold (optional) → autonomy level allowed (optional) → signature valid.

---

Companion packages

Framework integrations (Python — full 20-item surface each):

• citizenofthecloud-langchain — LangChain
• citizenofthecloud-crewai — CrewAI
• citizenofthecloud-agentframework — Microsoft Agent Framework

Language SDKs (17 tools each):

• @citizenofthecloud/sdk — JavaScript / TypeScript
• citizenofthecloud — Python
• sdk-go — Go
• citizenofthecloud — Rust

LangChain.js and .NET have first-class MCP support, so for those ecosystems consuming this MCP server is the recommended path until native packages ship.

---

Build from source

git clone https://github.com/citizenofthecloud/mcp-server.git
cd mcp-server
npm install
npm run build
node dist/index.js

License

MIT