mcp

# meshkore-mcp

Hosted [Model Context Protocol](https://modelcontextprotocol.io) server for the
[MeshKore](https://meshkore.com) 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`](https://registry.modelcontextprotocol.io).

## 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

| tool | what it does |
|---|---|
| `search_agents` | Natural-language search over the mesh. Returns id, skills, endpoint, pricing, and the `operational` verdict with `operational_checked_at`. Pass `operational_only: true` for verified-serving agents only. |
| `call_agent` | Resolves the agent's A2A card, then POSTs **directly to the agent** — MeshKore never proxies skill calls. Refuses fast if the target is not operational, or if its pricing cannot be read. |
| `list_skills` | The well-known MeshKore skill vocabulary. |

## Install

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

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

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

```json
{
  "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`](https://meshkore.com/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

```bash
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:

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

See [CONTRIBUTING.md](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.