CNSLabs/agreements-api-sdk

Shodai turns agreement definitions into machine-readable, verifiable coordination workflows for humans, products, and AI agents. Agreements carry readable terms plus participants, valid inputs, states, transitions, and history.
This repository supports builders using the TypeScript SDK, agents or tools using MCP, and the canonical Shodai Reference App built on top of the SDK.
Start Here
| Need | Start |
| --- | --- |
| Understand Shodai | Shodai Home · Developer Docs · Demo App |
| Get access | Dev Portal / API keys |
| Build | Choose SDK vs MCP · MCP quickstart · TypeScript SDK quickstart · End-to-end workflow |
**Hosted MCP:** https://shodai.network/mcp is the Shodai Agreements execution MCP endpoint. OAuth-capable clients connect through browser sign-in and consent for testnet access. The endpoint uses Streamable HTTP, requires an environment tool argument, supports environment-scoped API keys as a fallback, and has no hosted private-key custody.
**Packages and apps:** @shodai-network/agreements-api-client · @shodai-network/agreements-mcp-server · agreements-api-playground · shodai-reference-app · oauth-connect-cli (shodai-oauth)
Why Builders Use Shodai Agreements
- Shared agreement state that humans, applications, and agents can inspect.
- Deterministic next actions from authored states, inputs, issuers, and transitions.
- Validation and deployment preflight before signatures.
- EIP-712 signed authorization for deployment and participant inputs.
- State and input history for receipts and monitoring.
- Less repeated contract orchestration, indexing, and participant workflow plumbing.
Choose Your Path
| Path | Use it when | First success |
| --- | --- | --- |
| MCP / agent tools | An agent or MCP-capable client will work with agreements through hosted Streamable HTTP or local stdio. | Authenticate, read or list where permitted, validate an example, preflight deployment, and prepare deploy typed data. |
| TypeScript SDK | You are building a TypeScript application or service. | Authenticate, read or list agreements, validate an example, preflight deployment, and prove local EIP-712 signing readiness. |
Both paths converge on the same agreement lifecycle. After one quickstart works, run the end-to-end workflow.
Hosted MCP Endpoint
Configure Shodai as a remote Streamable HTTP MCP server:
Start the connection in an OAuth-capable client, then complete Shodai browser sign-in and consent. The hosted endpoint advertises the testnet authorization server, so use environment: "testnet" for this OAuth connection.
Clients without OAuth support can send Authorization: Bearer cns_pk_.... API keys only work in the environment where they were created; a production key can use environment: "production". Hosted MCP never receives private keys; write tools use externally signed EIP-712 permits or typed-data preparation.
An ordinary browser GET to /mcp may return 405 because the endpoint expects MCP protocol requests. MCP surfaces on docs.shodai.network are for docs and search only; https://shodai.network/mcp is the Agreements execution endpoint.
- MCP quickstart: docs.shodai.network/sdks/quickstart-with-mcp
- MCP package docs: packages/agreements-mcp-server/README.md
- Execution server card: shodai.network/.well-known/mcp/server-card.json
- MCP catalog: shodai.network/.well-known/mcp/catalog.json
What This Repository Contains
| Package or app | Location | Purpose |
| --- | --- | --- |
| @shodai-network/agreements-api-client | packages/agreements-api-client | Typed REST client for the Agreements API with viem permit-signing helpers. |