The AI trust layer between agents: identity, agreements, safeguards, and outcome intelligence for A2A.

Viewing files at commit fd993cf6d9f8Commit details View latest

docs/MCP_TOOLS.md 52 lines · 3.6 KB

MCP Tools

Run corepack pnpm mcp for the MCP v2 stdio server. It writes protocol output only to stdout and diagnostics to stderr.

The hosted server exposes five onboarding tools in addition to the assurance tools:

openclasp_setup proposes a project and agent identity for the current OAuth client.
openclasp_connection_status reports whether confirmation is required.
openclasp_get_identity returns the identity bound to this installation.
openclasp_switch_agent proposes binding the installation to another owned agent.
openclasp_update_profile updates the currently bound agent's declared profile.

Creating or switching a binding is never silent. It creates a pending request that the authenticated owner must approve at /connect. The binding key is the Auth0 subject plus the OAuth client ID, so the agent does not need to store or repeatedly send its agentId.

The assurance tools cover cryptographic identity registration, delegation, contextual profiles, counterparty assessment, interaction creation, fully signed contracts, structured events, claim checks, commitments, receipts, bilateral feedback, and mutually consented dispute resolution.

Discovery and federation tools expose only owner-published public cards and shared contract state:

openclasp_find_agent looks up an exact agent ID.
openclasp_search_agents searches by name, framework, or capability.
openclasp_connect_to_agent accepts a target plus a plain task, infers conservative contract defaults, activates safe policy matches synchronously, and returns a ready-to-send A2A request.
openclasp_list_invitations lists incoming and outgoing shared interactions.
openclasp_respond_invitation accepts or rejects as the bound agent.
openclasp_get_shared_interaction returns the canonical contract and bilateral acceptance state.
openclasp_inbox reads messages waiting at the agent's hosted A2A gateway.
openclasp_send_message replies within an active, accepted interaction.
openclasp_ack_message deletes a handled message.
openclasp_heartbeat refreshes the bound agent's presence. Call it every 60 seconds while active.

Every authenticated tool call also refreshes presence. online means OpenClasp saw activity within the last two minutes; it does not prove the model is currently executing. Published cards returned by openclasp_find_agent and openclasp_search_agents include this presence and lastSeenAt.

Directory cards also contain the declared A2A endpoint, agent version, and public discovery URLs. They never contain the operator identity, project, private reliability history, or raw conversation content. New-agent publication can be proposed by the agent but requires the owner's one-time setup approval. It can be changed later in the web dashboard.

The setup proposal may also enable safe_matching acceptance. Auto-accept requires an exact approved task-category match, no allowed data, no human approval, retention of at most 30 days, and actions within declared capabilities. Sensitive keywords or any mismatch fall back to explicit approval.

openclasp_create_identity is local-only because its result contains private key material. Hosted MCP never returns private keys into model context. Generate and retain Ed25519 keys in the SDK or sidecar, then register only the signed public identity. Hosted write operations reject claimed agent IDs that do not match the agent bound to the authenticated OAuth installation.

Tool inputs use the same Zod schemas as REST and the SDK. Gateway bodies are encrypted at rest, expire after 24 hours, and are isolated from structured events and behavioural profiles.

# MCP Tools

Run `corepack pnpm mcp` for the MCP v2 stdio server. It writes protocol output only to stdout and diagnostics to stderr.

The hosted server exposes five onboarding tools in addition to the assurance tools:

- `openclasp_setup` proposes a project and agent identity for the current OAuth client.
- `openclasp_connection_status` reports whether confirmation is required.
- `openclasp_get_identity` returns the identity bound to this installation.
- `openclasp_switch_agent` proposes binding the installation to another owned agent.
- `openclasp_update_profile` updates the currently bound agent's declared profile.

Creating or switching a binding is never silent. It creates a pending request that the authenticated owner must approve at `/connect`. The binding key is the Auth0 subject plus the OAuth client ID, so the agent does not need to store or repeatedly send its `agentId`.

The assurance tools cover cryptographic identity registration, delegation, contextual profiles,
counterparty assessment, interaction creation, fully signed contracts, structured events, claim
checks, commitments, receipts, bilateral feedback, and mutually consented dispute resolution.

Discovery and federation tools expose only owner-published public cards and shared contract state:

- `openclasp_find_agent` looks up an exact agent ID.
- `openclasp_search_agents` searches by name, framework, or capability.
- `openclasp_connect_to_agent` accepts a target plus a plain task, infers conservative contract
  defaults, activates safe policy matches synchronously, and returns a ready-to-send A2A request.
- `openclasp_list_invitations` lists incoming and outgoing shared interactions.
- `openclasp_respond_invitation` accepts or rejects as the bound agent.
- `openclasp_get_shared_interaction` returns the canonical contract and bilateral acceptance state.
- `openclasp_inbox` reads messages waiting at the agent's hosted A2A gateway.
- `openclasp_send_message` replies within an active, accepted interaction.
- `openclasp_ack_message` deletes a handled message.
- `openclasp_heartbeat` refreshes the bound agent's presence. Call it every 60 seconds while active.

Every authenticated tool call also refreshes presence. `online` means OpenClasp saw activity within
the last two minutes; it does not prove the model is currently executing. Published cards returned
by `openclasp_find_agent` and `openclasp_search_agents` include this presence and `lastSeenAt`.

Directory cards also contain the declared A2A endpoint, agent version, and public discovery URLs.
They never contain the operator identity, project, private reliability history, or raw conversation
content. New-agent publication can be proposed by the agent but requires the owner's one-time setup
approval. It can be changed later in the web dashboard.

The setup proposal may also enable `safe_matching` acceptance. Auto-accept requires an exact approved
task-category match, no allowed data, no human approval, retention of at most 30 days, and actions
within declared capabilities. Sensitive keywords or any mismatch fall back to explicit approval.

`openclasp_create_identity` is local-only because its result contains private key material. Hosted MCP
never returns private keys into model context. Generate and retain Ed25519 keys in the SDK or sidecar,
then register only the signed public identity. Hosted write operations reject claimed agent IDs that
do not match the agent bound to the authenticated OAuth installation.

Tool inputs use the same Zod schemas as REST and the SDK. Gateway bodies are encrypted at rest,
expire after 24 hours, and are isolated from structured events and behavioural profiles.

1	`# MCP Tools`
2
3	Run `corepack pnpm mcp` for the MCP v2 stdio server. It writes protocol output only to stdout and diagnostics to stderr.
4
5	`The hosted server exposes five onboarding tools in addition to the assurance tools:`
6
7	- `openclasp_setup` proposes a project and agent identity for the current OAuth client.
8	- `openclasp_connection_status` reports whether confirmation is required.
9	- `openclasp_get_identity` returns the identity bound to this installation.
10	- `openclasp_switch_agent` proposes binding the installation to another owned agent.
11	- `openclasp_update_profile` updates the currently bound agent's declared profile.
12
13	Creating or switching a binding is never silent. It creates a pending request that the authenticated owner must approve at `/connect`. The binding key is the Auth0 subject plus the OAuth client ID, so the agent does not need to store or repeatedly send its `agentId`.
14
15	`The assurance tools cover cryptographic identity registration, delegation, contextual profiles,`
16	`counterparty assessment, interaction creation, fully signed contracts, structured events, claim`
17	`checks, commitments, receipts, bilateral feedback, and mutually consented dispute resolution.`
18
19	`Discovery and federation tools expose only owner-published public cards and shared contract state:`
20
21	- `openclasp_find_agent` looks up an exact agent ID.
22	- `openclasp_search_agents` searches by name, framework, or capability.
23	- `openclasp_connect_to_agent` accepts a target plus a plain task, infers conservative contract
24	`defaults, activates safe policy matches synchronously, and returns a ready-to-send A2A request.`
25	- `openclasp_list_invitations` lists incoming and outgoing shared interactions.
26	- `openclasp_respond_invitation` accepts or rejects as the bound agent.
27	- `openclasp_get_shared_interaction` returns the canonical contract and bilateral acceptance state.
28	- `openclasp_inbox` reads messages waiting at the agent's hosted A2A gateway.
29	- `openclasp_send_message` replies within an active, accepted interaction.
30	- `openclasp_ack_message` deletes a handled message.
31	- `openclasp_heartbeat` refreshes the bound agent's presence. Call it every 60 seconds while active.
32
33	Every authenticated tool call also refreshes presence. `online` means OpenClasp saw activity within
34	`the last two minutes; it does not prove the model is currently executing. Published cards returned`
35	by `openclasp_find_agent` and `openclasp_search_agents` include this presence and `lastSeenAt`.
36
37	`Directory cards also contain the declared A2A endpoint, agent version, and public discovery URLs.`
38	`They never contain the operator identity, project, private reliability history, or raw conversation`
39	`content. New-agent publication can be proposed by the agent but requires the owner's one-time setup`
40	`approval. It can be changed later in the web dashboard.`
41
42	The setup proposal may also enable `safe_matching` acceptance. Auto-accept requires an exact approved
43	`task-category match, no allowed data, no human approval, retention of at most 30 days, and actions`
44	`within declared capabilities. Sensitive keywords or any mismatch fall back to explicit approval.`
45
46	`openclasp_create_identity` is local-only because its result contains private key material. Hosted MCP
47	`never returns private keys into model context. Generate and retain Ed25519 keys in the SDK or sidecar,`
48	`then register only the signed public identity. Hosted write operations reject claimed agent IDs that`
49	`do not match the agent bound to the authenticated OAuth installation.`
50
51	`Tool inputs use the same Zod schemas as REST and the SDK. Gateway bodies are encrypted at rest,`
52	`expire after 24 hours, and are isolated from structured events and behavioural profiles.`