@kya-os/mcp weekly downloads statistics

KYA-OS: agent identity, delegation, and proof. This repo is the MCP binding.

What KYA-OS is

KYA-OS (Know Your Agent Operating System) is an identity, authority, and accountability layer that other agent-facing protocols adopt, so that any time an agent acts you can verify who called (agent identity), under what authority (delegation chain rooted at a Responsible Party, plus consent where required), and what they did (signed proofs composing into audit trails).

The shape of the contribution is roughly analogous to TLS. TLS is not a transport, it is a security layer that transports adopt. KYA-OS is not a transport or a runtime, it is an identity and accountability layer that host protocols embed.

Three jobs, six primitives:

• Identity. Every agent and every server holds a Decentralized Identifier (did:key, did:web): a stable, cryptographically-controlled identifier that the agent can prove it owns, and that credentials can be issued against. Without this, there is nothing to bind authority to or hold accountable. • Authority. W3C Verifiable Credentials carrying scoped, revocable delegation chains rooted at a Responsible Party. Per-tool consent gating for actions that require explicit human approval. • Accountability. Detached JWS proofs over canonicalized request/response hashes, composing into tamper-evident audit trails. Invisible to the LLM, verifiable by anyone holding the agent's DID.

Note on the name. This protocol was previously known as MCP-Identity / MCP-I. The rename to KYA-OS reflects the protocol's binding-agnostic scope. See the [Unreleased] entry in CHANGELOG.md for the full rationale.

What this repo is

@kya-os/mcp is the MCP binding of KYA-OS, the reference implementation for Model Context Protocol servers, and the first binding to ship.

KYA-OS primitives are intended to embed in three kinds of host surface:

1. Transport bindings. Wire protocols an agent's calls ride over (e.g. MCP, HTTPS, gRPC, SMTP). 2. Runtime bindings. Agent harnesses where the loop runs and tool invocations can be wrapped uniformly. 3. Manifest / assertion embeddings. Host formats that already carry signed assertions, where a KYA-OS proof can serve as one assertion type (e.g. C2PA-track content provenance manifests).

The MCP binding ships first because MCP is the most concentrated agent-to-tool RPC surface today. Additional bindings will be specified in the working group as they reach consensus.

The KYA-OS protocol itself is defined in SPEC.md. Binding-specific behavior is called out so future bindings can diverge cleanly where they need to.

Upgrading to 1.20: proofs need a KYA-OS transport

Breaking for servers without a KYA-OS transport. From 1.20, every response proof (under the default body profile as under the envelope profile) is made where the KYA-OS transport sends the result, after the MCP SDK has finished it. While no KYA-OS transport is open for the middleware, wrapWithProof, wrapWithDelegation, withPolicyGate and proveOutcome throw before they run anything.

| Your setup | What to do |

| withKyaOs(server, …) before server.connect() | Nothing. | | Low-level Server with createKyaOsMiddleware | await server.connect(createKyaOsTransport(transport, kyaos)). It proves every tool's result, unwrapped tools included (unproven on 1.19.0); its third argument adds tools to leave unproven. | | A script or test that calls a wrapped handler directly | const local = serveInProcess(kyaos); const call = local.tool('name', handler); await call(args); await local.close(); | | withKyaOs with proofAllTools: false | Leave it on; list tools to leave unproven in excludeTools. | | withKyaOs after connect() | Call it before connect(). | | Reading the proof inside the handler | The transport adds it when the result is sent; read it from what the client receives. | | MCP task results fetched later | A result is proved the first time the same middleware sends it, within pendingProofTtlMs (default five minutes, at most 2147483647 ms); raise it for later fetches. |

See the changelog for the details.

Migrate any MCP server in 2 lines

Before, a standard MCP server with no identity or proofs:

After, every tool response now carries a signed cryptographic proof:

That's it. withKyaOs auto-generates an Ed25519 identity, registers the _kyaos protocol tool, and wraps the transport so every tool response includes a detached JWS proof in _meta. Invisible to the LLM, verifiable by anyone.

See the full working example: examples/context7-with-kya-os, a real MCP server (Context7) migrated with exactly 2 lines of code.

Protect tools with human consent

Some tools shouldn't run without a human saying "yes." KYA-OS adds per-tool authorization using W3C Verifiable Credentials:

When an agent calls checkout without a delegation credential, it gets back a needs_authorization response with a consent URL. The human approves, a scoped credential is issued, and the agent retries, now authorized.

Try it yourself: examples/consent-basic walks through the full consent flow end-to-end.

Prove the outcomes your own code decides

A server that enforces authorization itself, checking OAuth scopes in the tool handler for example, returns its own challenges and denials as tool results. withKyaOs proves the results it can attribute, but it sends an error result its own gates did not produce as the handler returned it, without a proof. proveOutcome gives that result the proof the gates attach to theirs, with the same claims, _meta keys and audit events:…