Purpose
Shodai Agreements SDK + MCP turns agreement definitions into machine-readable, verifiable coordination workflows for people, products, and AI agents. The agreement itself carries readable terms, as well as parties, valid inputs, state, state transitions, and history.
This repository serves three types of users: developers using the TypeScript SDK, agents or tools using MCP, and the Shodai reference application built on the SDK.
Main capabilities
- Shared agreement state, inspectable by humans, applications, and agents.
- Deterministic next actions based on the written states, inputs, issuers, and transitions.
- Validation and deployment preflight before signing.
- Support for EIP-712 signed authorization, used for deployment and party inputs.
- Provides state and input history for credentials and monitoring.
- Reduces repetitive contract orchestration, indexing, and party workflow pipeline setup.
Usage
Hosted MCP endpoint
Configure Shodai as a remote Streamable HTTP MCP server:
- Initiate a connection in an OAuth-capable client, then complete Shodai browser login and authorization consent. The hosted endpoint declares a testnet authorization server, so this OAuth connection uses environment: "testnet".
- Clients that do not support OAuth can send Authorization: Bearer cns_pk_.... An API key is only valid in the environment in which it was created; production keys can use environment: "production". Hosted MCP never receives private keys; write tools use externally signed EIP-712 permits or typed data preparation.
- A normal browser GET request to /mcp may return 405, because this endpoint expects MCP protocol requests. The MCP interface on docs.shodai.network is for documentation and search only;https://shodai.network/mcp is the agreement execution endpoint.
MCP quickstart: docs.shodai.network/sdks/quickstart-with-mcp MCP package documentation: 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
Install the TypeScript SDK
Most TypeScript users should install the published npm package, not this monorepo:
npm install @shodai-network/agreements-api-client
If you need the built-in permit signing helpers for deployment and input submission, add viem:
npm install viem
Create a client using a named Shodai environment:
SDK usage and API lifecycle documentation are located at packages/agreements-api-client/README.md. For constructor options, methods, signing helpers, diagnostics, and exports, see the TypeScript client reference.
Run MCP locally
Use the published MCP package for a local stdio client:
Local stdio mode uses AGREEMENTS_API_ENVIRONMENT; hosted MCP uses the environment tool parameter. For self-hosting, environment variables, tools, resources, prompts, and Inspector usage, see packages/agreements-mcp-server/README.md.
Agreement lifecycle
For a guided walkthrough of validation, deployment, signed input submission, state reading, and input history, use the end-to-end workflow.
Agreements API environments
The SDK prefers named environments over raw hosts:
Built-in mappings:
- testnet -> https://test-api.shodai.network
- production -> https://api.shodai.network
API keys are distinguished by environment. Testnet keys go with testnet, production keys go with production.
The client still supports baseUrl as an advanced override, for local proxies, internal gateways, or non-standard deployments. It will still automatically add /v0/*.
Local development
The default dev command starts the Shodai reference application. Its backend defaults to http://localhost:4199，前端默认为 http://localhost:5184/agreements/。
Stop the reference application dev stack:
For the required local environment files, see apps/shodai-reference-app/README.md.
Explicitly run the API playground:
The playground defaults to http://localhost:5176。若该端口已被占用，可在另一端口启动 playground:
For local browser development, the playground is environment-first and defaults to testnet. Use the in-app environment selector to switch between the hosted testnet and production API targets.
Optional package-level verification commands:
For full environment configuration, see apps/agreements-api-playground/README.md.
Limitations
- The hosted MCP does not hold private keys.
- Hosted MCP browser OAuth and direct API delegated OAuth connection paths are supported; x402 payment is not the current setup path.
- The Shodai protocol does not claim legal finality or fully autonomous execution capability.
- Shodai will not move value on unauthorized signing inputs.
Open source project notes
- API client consumer documentation: packages/agreements-api-client/README.md
- API client maintainer notes: packages/agreements-api-client/DEVELOPMENT.md
- MCP server documentation: packages/agreements-mcp-server/README.md
- Playground documentation: apps/agreements-api-playground/README.md
- Root license: Apache-2.0
- MCP package license: MIT
