@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

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

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

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