# CNSLabs/agreements-api-sdk [Health: Active]

**Category:** 🤝 Agreements & Coordination  
**Repository:** https://github.com/CNSLabs/agreements-api-sdk  
**GitHub Stars:** 2  
**npm Downloads (last month):** 60  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cnslabs-agreements-api-sdk

## Description
Remote Streamable HTTP and local stdio MCP server for defining, validating, deploying, and operating machine-readable agreements with EIP-712 permit preparation, signed participant inputs, state reads, and input history.

## Tools
Capabilities this server exposes over MCP:

- **list_agreements** — Lists agreement summaries visible to the current API key. Supports pagination (cursor + limit), filtering by chain and state, and sorting. Returns summaries only; use get_agreement for the full record.
- **get_agreement** — Returns a single agreement record, including the full authored agreement JSON and hosted record context (participants, observers, owner, deployment address).
- **get_agreement_document** — Returns the rendered hosted prose document for an agreement by documentId, including content type, display name, chain, docUri, and agreement record references. Use documentId from list_agreements/get_agreement or from prepare_deployment_typed_data.
- **get_agreement_state** — Returns the current state of an agreement. For deployed agreements, interpret the state against the states defined in the authored agreement lifecycle (execution.states). Use this to poll for transitions after submitting an input.
- **get_input_history** — Returns recorded input submissions for an agreement, with pagination and filtering. Use this to inspect which events have been submitted and whether each is PENDING, FINALIZED, or FAILED.
- **validate_agreement** — Checks only the authored agreement JSON document and returns participant variable keys, input IDs, state IDs, and warnings. This does not validate deployment values, participant wallet addresses, signer, or permit data — use preflight_deployment for that. Iterate on the agreement JSON until this returns no blocking warnings. Requires the agreements.write scope.
- **preflight_deployment** — Checks whether authored agreement JSON plus target chain, deployment values, participant wallet mappings, and observer context are ready for deployment. This does not deploy the agreement and does not require a signature. Always run this before signing a deploy permit. Requires the agreements.write scope.
- **deploy_agreement** — Deploys authored agreement JSON using an EIP-712 permit; the API submits the on-chain transaction and returns the deployed agreement record. Provide a pre-signed permit (signer, deadline, signature), or call prepare_deployment_typed_data first to obtain the payload to sign. Always run preflight_deployment before deploying. Requires the agreements.write scope.
- **submit_input** — Submits a signed input to a deployed agreement, advancing its on-chain lifecycle. The input ID and values must match an input defined by the agreement JSON, and the signer must be allowed by that input. Provide a pre-signed permit (signer, deadline, signature), or call prepare_input_typed_data first. Requires the agreements.write scope.
- **prepare_deployment_typed_data** — Builds the exact EIP-712 payload that must be signed to authorize deployment of the given agreement JSON. Sign the returned typedData with the deploying wallet (eth_signTypedData_v4 / viem signTypedData), then call deploy_agreement with signer, deadline, and the signature components. No transaction is sent and nothing is stored. Reads the signer nonce from the target chain.
- **prepare_input_typed_data** — Builds the exact EIP-712 payload that must be signed to authorize submitting an input to a deployed agreement. Sign the returned typedData with a wallet allowed by the input definition, then call submit_input with signer, deadline, and the signature components. No transaction is sent and nothing is stored. Reads the agreement record and signer nonce.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agreements-api-sdk": {
    "command": "npx",
    "args": ["-y","@shodai-network/agreements-mcp-server"],
    "env": {
      "AGREEMENTS_API_KEY": "",
      "AGREEMENTS_API_ENVIRONMENT": ""
    }
  }
}
```

**Requires environment variables:** `AGREEMENTS_API_KEY`, `AGREEMENTS_API_ENVIRONMENT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What CNSLabs/agreements-api-sdk MCP server does

The CNSLabs/agreements-api-sdk MCP server exposes the Shodai Agreements API as MCP tools for agreement lifecycle work. It supports listing visible agreements, retrieving full agreement records, reading hosted documents, checking current state, and inspecting submitted input history.

For authoring and deployment, the server can validate agreement JSON, run deployment preflight checks, prepare deployment signing data, and submit a deployment with a completed EIP-712 permit. For deployed agreements, it can prepare typed data for participant inputs and submit externally signed inputs that match the agreement’s input definitions and signer permissions.

## How it works

The repository supports two MCP connection modes. Hosted access uses the Streamable HTTP endpoint at `https://shodai.network/mcp`. Local access uses the published `@shodai-network/agreements-mcp-server` package through stdio. Hosted clients provide an `environment` tool argument, while local configuration uses an environment variable.

Authentication can use an OAuth-capable client with browser sign-in and consent, or an environment-scoped API key. The server does not hold private keys for hosted MCP use. Instead, typed-data preparation returns the exact EIP-712 payload for an external wallet to sign. The resulting signer, deadline, and signature components are then passed to the deployment or input-submission tool.

A typical deployment sequence is agreement validation, deployment preflight, typed-data preparation, external signing, and deployment. Input submission follows the same pattern: prepare typed data, sign with an allowed wallet, submit the signed input, then poll agreement state or inspect input history.

## Setup and configuration

For local stdio use, configure an MCP client to run `npx -y @shodai-network/agreements-mcp-server`. Set `AGREEMENTS_API_KEY` to an API key and `AGREEMENTS_API_ENVIRONMENT` to `testnet` or `production`. Keys are scoped to their environment, so the selected environment must match the key.

Hosted access uses `https://shodai.network/mcp` and requires `environment: "testnet"` for the documented OAuth connection. Clients without OAuth support can send a bearer API key created for the selected environment. The hosted endpoint expects MCP protocol requests; a normal browser GET may return HTTP 405.

## Tools and capabilities

The CNSLabs/agreements-api-sdk MCP server provides tools for:

- Listing and retrieving agreement records and rendered documents.
- Reading agreement state and paginated input history.
- Validating authored JSON and checking deployment readiness.
- Preparing and submitting deployment permits.
- Preparing and submitting signed participant inputs.
- Filtering and paginating agreement or input results where supported.

Validation of authored JSON is separate from deployment preflight. Validation does not check wallet mappings, deployment values, signer details, or permit data. Preflight does not deploy and does not require a signature.

## Limitations and notes

Write tools require the `agreements.write` scope. Deployment and input submission require signatures produced outside the server. Agreement inputs must match the authored definition, and the signer must be authorized for the selected input. State values for deployed agreements should be interpreted using the lifecycle states defined in the authored agreement JSON.

The server returns agreement summaries from listing calls; use the individual agreement retrieval tool for the complete record. Hosted MCP does not provide private-key custody, so an agent workflow must have access to an external signing method before it can complete deployment or input submission.

_Full upstream README: https://allmcps.com/mcp/cnslabs-agreements-api-sdk/readme_