Labsco
CNSLabs logo

Shodai Agreements

★ 1

from CNSLabs

MCP server for creating, coordinating, and executing agreements: commitments, escrow, and multi-party decision workflows across humans, agents, and organizations.

🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#payments#devops#git#maps#monitoring

Shodai Agreements SDK + MCP

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

NeedStart
Understand ShodaiShodai Home · Developer Docs · Demo App
Get accessDev Portal / API keys
BuildChoose 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. It uses Streamable HTTP, bearer API-key auth, an environment tool argument, environment-scoped keys, and no hosted private-key custody.

Packages and apps: @cns-labs/agreements-api-client · @cns-labs/agreements-mcp-server · agreements-api-playground · shodai-reference-app

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

PathUse it whenFirst success
MCP / agent toolsAn 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 SDKYou 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:

URL:
https://shodai.network/mcp

Auth:
Authorization: Bearer $SHODAI_API_KEY

Key shape:
cns_pk_...

Required API-calling tool argument:
environment: "testnet" | "production"

API keys only work in the environment where they were created. 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.

What This Repository Contains

Package or appLocationPurpose
@cns-labs/agreements-api-clientpackages/agreements-api-clientTyped REST client for the Agreements API with viem permit-signing helpers.
@cns-labs/agreements-mcp-serverpackages/agreements-mcp-serverLocal MCP server package aligned with the hosted Agreements execution MCP surface.
agreements-api-playgroundapps/agreements-api-playgroundReference Vite app for browser API experimentation and SDK workflow examples.
shodai-reference-appapps/shodai-reference-appFull-stack React/Nest/Mongo reference implementation for developer platform auth, Agreements API usage, agreement lifecycle UX, signing, persistence, and webhook reconciliation.

Run MCP Locally

Use the published MCP package for local stdio clients:

{
  "mcpServers": {
    "shodai-agreements": {
      "command": "npx",
      "args": ["-y", "@cns-labs/agreements-mcp-server"],
      "env": {
        "AGREEMENTS_API_KEY": "YOUR_API_KEY",
        "AGREEMENTS_API_ENVIRONMENT": "testnet"
      }
    }
  }
}

Local stdio mode uses AGREEMENTS_API_ENVIRONMENT; hosted MCP uses the environment tool argument. See packages/agreements-mcp-server/README.md for self-hosting, environment variables, tools, resources, prompts, and Inspector usage.

Agreement Lifecycle

PhaseTypeScript SDKMCP
Author agreement JSONUse complete agreement JSON artifacts and examples.Read example resources or use the authoring prompt.
Validate structureclient.validateTemplate(...)validate_agreement
Preflight deploymentclient.validateDeployment(...)preflight_deployment
Prepare or sign deployment permitSDK signing helpers with viemprepare_deployment_typed_data and external signing
DeploydeployAgreementWithPermit(...) or client.deployWithPermit(...)deploy_agreement with signed permit fields
Read stateclient.getAgreementState(...)get_agreement_state
Prepare or sign input permitSDK input-signing helpersprepare_input_typed_data and external signing
Submit inputsubmitAgreementInputWithPermit(...) or client.submitAgreementInput(...)submit_input with signed permit fields
Inspect historyclient.listAgreementInputs(...)get_input_history

For a guided run through validation, deployment, signed input submission, state reads, and input history, use the end-to-end workflow.

Agreements API Environments

The SDK prefers a named environment instead of a raw host:

const client = new ApiClient({
  environment: 'testnet',
  apiKey: process.env.AGREEMENTS_API_KEY,
});

Built-in mappings:

  • testnet -> https://test-api.shodai.network
  • production -> https://api.shodai.network

API keys are environment-scoped. Use a testnet key with testnet and a production key with production.

The client still supports baseUrl as an advanced override for local proxies, internal gateways, or non-standard deployments. It continues to add /v0/* automatically.

Local Development

# from the repository root
pnpm install
pnpm build
pnpm dev

The default dev command starts the Shodai Reference App. Its backend defaults to http://localhost:4199 and its frontend defaults to http://localhost:5184/agreements/.

Stop the reference app dev stack with:

pnpm dev:stop

See apps/shodai-reference-app/README.md for the required local environment files.

Run the API playground explicitly with:

pnpm dev:playground

The playground defaults to http://localhost:5176. If that port is already in use, start the playground on another port:

pnpm --filter agreements-api-playground exec vite --host 127.0.0.1 --port 4176

For local browser development, the playground is environment-first and defaults to testnet. Use the in-app environment selector to switch between hosted testnet and production API targets.

Optional package-specific validation commands:

pnpm --filter @cns-labs/agreements-api-client run lint
pnpm --filter @cns-labs/agreements-mcp-server test

See apps/agreements-api-playground/README.md for the full environment configuration.

Boundaries

Hosted MCP does not hold private keys. OAuth/session auth and x402 payments are not current setup paths. Shodai agreements do not claim legal finality or fully autonomous enforcement. Shodai does not move value without authorized signed inputs.

Open Source Project Notes