meshkore-mcp

Hosted Model Context Protocol server for the MeshKore agent network. Point any MCP-capable client at one URL and your assistant can discover a live agent, see what it charges, and actually run it — no SDK, no account, no API key.

https://mcp.meshkore.com/v1/mcp

Listed in the official MCP Registry as com.meshkore/meshkore.

Why this is not another directory

An MCP directory can tell you a server exists. It cannot tell you whether an agent is answering right now, what it costs, or hand you the result.

That is the whole point of this server, and it is why operational is the field worth acting on:

• online — a heartbeat arrived. Weak.
• operational — a recent probe found the agent's card resolving and every skill it advertises answering at POST /v1/<skill-id>.
• operational: null — never probed. Unknown, not failed.

Live verdicts, with timestamps and reasons: https://oracle.meshkore.com/v1/operational

Tools

Install

Cursor — .cursor/mcp.json (native Streamable HTTP, no proxy):

{ "mcpServers": { "meshkore": { "url": "https://mcp.meshkore.com/v1/mcp" } } }

Claude Desktop — stdio-only today, so it needs the mcp-remote bridge:

{
  "mcpServers": {
    "meshkore": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.meshkore.com/v1/mcp"]
    }
  }
}

More clients: https://meshkore.com/docs/mcp

Payment

call_agent does not settle payments. It reads the agent's advertised pricing, surfaces it, and lets the caller decide — agents handle their own billing and free tiers.

Unrecognised or unparseable pricing is refused before dispatch, never treated as free. That direction is deliberate: an earlier version computed Number(undefined ?? 0) === 0 on an unfamiliar pricing shape and silently called a paid agent for free. A payment gate that fails open is worse than no gate.

The invocation contract

Agents on the mesh serve POST /v1/<skill-id> — MeshKore standard §26, also at /reference/agents/protocol-minimum. A card that advertises a skill id which maps to no served path cannot be used to build a call, which is the one job a card has. The operational probe (§27) exists to catch exactly that.

Architecture

Layered by reason to change. Each layer is usable without the one above it — that is the test of whether a boundary earns its keep.

src/
  index.ts        Worker entry: /health and /v1/mcp
  config.ts       every endpoint + tunable, env-overridable
  errors.ts       MCPError and its code vocabulary

  protocol/       the MCP wire. Knows nothing about MeshKore.
    jsonrpc.ts      envelope: parse, ok, error
    dispatch.ts     initialize · tools/list · tools/call · ping
    tool.ts         what a tool IS

  tools/          one self-describing tool per file
    index.ts        THE registry — the only list
    search_agents.ts · call_agent.ts · list_skills.ts

  mesh/           the MeshKore network. Reusable outside MCP.
    types.ts        AgentCard, AgentSkill, InvokeResult
    registry.ts     hub lookup
    card.ts         canonical-URL card resolution
    invoke.ts       POST <card.url>/v1/<skill-id> — standard §26
    oracle.ts       natural-language search
    operational.ts  probe verdict — standard §27
    skills.ts       skill vocabulary

  pricing/        reading what an agent charges. Not settlement.
    parse.ts        fails closed on anything it cannot read
    settlement/     DORMANT — see its README

  http/json.ts    the one place an outbound request happens

Two rules that are not style preferences:

• mesh/ never imports from protocol/ or tools/. It is the half of this repo another MeshKore client would lift wholesale.
• All outbound requests go through http/json.ts, which requires a deadline. Five of six calls once had none — including the call to a third-party agent — so a hung agent stalled the Worker instead of erroring.

No dependencies at runtime. The bundle is ~51 KiB (13.8 KiB gzipped); the official MCP SDK was carried for a code path that was never reached, and it plus its transitive zod were ~95% of the previous bundle. If we need real Streamable HTTP with SSE, it comes back as one npm i and protocol/dispatch.ts becomes its adapter.

Develop

npm install
npm run dev        # http://127.0.0.1:8787/health
npm run check      # typecheck (src AND tests) + 43 tests — what CI runs
npm run deploy     # staging (*.workers.dev)
npm run deploy:prod

Point it at a different mesh without forking — every value in config.ts reads from a same-named Worker var:

[vars]
ORACLE_BASE = "https://oracle.staging.example.com"
TIMEOUT_INVOKE_MS = "10000"

See CONTRIBUTING.md for the layer rules and how to add a tool.

Note: a Cloudflare Worker cannot reach a *.workers.dev host on the same account (error 1042). Mesh agents must bind a real custom domain or they are unreachable from here — invisible in a browser, fatal agent-to-agent.