# Agent tool adapter — GeniusFlow federation

No signup. Point agents at the live federation URL.

**How an agent finds this:** GET `https://geniusflow-federation.vercel.app/` (or `/.well-known/geniusflow.json` or `/llms.txt`) → read `tool_adapter`.

| Surface | URL |
|---------|-----|
| **Base** | `https://geniusflow-federation.vercel.app` |
| **OpenAPI 3** | https://geniusflow-federation.vercel.app/openapi.json |
| **Status / SLA** | https://geniusflow-federation.vercel.app/api/status |
| **Agent descriptor** | https://geniusflow-federation.vercel.app/api/agent |
| **llms.txt** | https://geniusflow-federation.vercel.app/llms.txt |
| **This doc (live)** | https://geniusflow-federation.vercel.app/docs/AGENT_TOOL_ADAPTER.md |
| **SLA doc (live)** | https://geniusflow-federation.vercel.app/docs/FEDERATION_SLA.md |
| **Proof shape (live)** | https://geniusflow-federation.vercel.app/docs/ATTESTATION_PROOF_SHAPE.md |

Covered endpoints: `dossier`, `report_feed`, `cite`, `verify`, `package`, `darshan`, `return_wire` (GET), plus `status` / `openapi`.

Protocol membership surfaces on the same origin:

| Network | Surface | URL |
|---------|---------|-----|
| **MCP** | Remote server | https://geniusflow-federation.vercel.app/api/mcp |
| **MCP** | Registry declaration | https://geniusflow-federation.vercel.app/server.json |
| **A2A** | Agent card | https://geniusflow-federation.vercel.app/.well-known/agent-card.json |
| **A2A** | JSON-RPC endpoint | https://geniusflow-federation.vercel.app/api/a2a |
| **ERC-8004** | Endpoint-domain proof | https://geniusflow-federation.vercel.app/.well-known/agent-registration.json |

## Option A — MCP remote (nothing to install)

```bash
curl -sS https://geniusflow-federation.vercel.app/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400
```

Streamable HTTP, JSON-RPC 2.0, POST only, stateless: no session header, no SSE stream.
Declares the `tools` capability only. Not declared and not implemented: resources,
prompts, completions, sampling, logging.

In an MCP client config:

```json
{
  "mcpServers": {
    "geniusflow-federation": {
      "url": "https://geniusflow-federation.vercel.app/api/mcp"
    }
  }
}
```

## Option B — MCP local stdio

Copy into Cursor / Claude Desktop MCP settings (adjust absolute path):

```json
{
  "mcpServers": {
    "geniusflow-federation": {
      "command": "python3",
      "args": [
        "/Users/YOU/Desktop/GENIUSFLOW_OS/workspace/geniusflow/engine/mcp/federation_mcp_server.py"
      ],
      "env": {
        "GENIUSFLOW_FEDERATION_URL": "https://geniusflow-federation.vercel.app"
      }
    }
  }
}
```

Tools: `gf_status`, `gf_dossier`, `gf_report_feed`, `gf_cite`, `gf_verify`, `gf_package`, `gf_darshan`, `gf_return_wire`, `gf_openapi`.

Smoke:

```bash
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | python3 engine/mcp/federation_mcp_server.py | head -c 400
```

Public mirror of this file, for the registry entry: https://github.com/Kaydeep0/eigenstate-research/tree/main/mcp

## Option C — A2A

```bash
curl -sS https://geniusflow-federation.vercel.app/api/a2a \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":
      {"messageId":"1","role":"ROLE_USER","parts":[{"text":"dossier CIRCLE"}]}}}' | head -c 300
```

Skills, all of which the endpoint actually answers: `settlement-claim-verify`,
`package-disposition`, `entity-dossier`, `federation-status`. Anything else is refused by
name rather than improvised. Stateless: `SendMessage` returns a Message, never a Task, and
the card declares `streaming` and `pushNotifications` false.

The card is unsigned on purpose. A JWS binds a card to a key without binding the key to
anyone, and a valid card replayed from another runtime gives the callee no signal. Instead
the card declares a probe-receipt extension naming the four limbs a verifier can genuinely
observe, and the node publishes its own receipt at `/.well-known/agent-registration.json`
where limb three currently refuses.

## Option D — OpenAPI only

```bash
curl -sS https://geniusflow-federation.vercel.app/openapi.json | jq .info
# Import that URL into any OpenAPI-capable agent / codegen.
```

## Option E — LangChain (optional thin wrapper)

```python
from engine.mcp.federation_langchain_tools import federation_tools
tools = federation_tools()  # needs langchain-core
```

## Agent discipline

1. Take `expected` only from published `claims[].grounding` — never invent from report HTML.
2. Use `/api/package` for admit/refuse; read `proof` / `proof_shape` (`docs/ATTESTATION_PROOF_SHAPE.md`).
3. Check `/api/status` when jobs look blind — tier is `best_effort_vercel` (`docs/FEDERATION_SLA.md`).