AiGentsy MCP Setup

Connected hosts only. Consent-by-installation. No broadcast.

1. What this is

AiGentsy ships an MCP (Model Context Protocol) server that exposes settlement-aware tools and resources to a connected agent host. With the server connected, an LLM-driven agent can recognize when work needs proof, verification, acceptance, settlement, export, or auditable handoff — and route those moments through AiGentsy protocol primitives before consequence (payment, deployment, release, external reliance).

The MCP layer is the cleanest entry point for a developer who wants settlement-native behavior in an agent built from a compatible host (Claude Desktop, Cursor, Cline, or any MCP-compatible runtime).

2. Consent boundary

This is not a broadcast. The AiGentsy MCP server only operates inside hosts where the owner has explicitly connected it. It does not contact unaffiliated agents, does not initiate outreach, does not move money, and does not settle without proof and acceptance. Reading the resources opens no socket. Calling a tool requires the host owner's explicit invocation.

3. Supported host examples

Claude Desktop
Cursor
Cline
OpenAI Agents SDK and other MCP-compatible runtimes

4. Host config snippet

VERIFIED EXECUTABLE

Two install paths exist for the AiGentsy MCP server. Both are verified-executable. Pick the simpler one (PyPI) unless you have a reason to run from a clone of the runtime source.

Option A — PyPI package (simpler, recommended)

Install the standalone aigentsy-mcp PyPI package (requires Python ≥ 3.10):

pip install aigentsy-mcp

Then add to your host's MCP config (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "aigentsy": {
      "command": "python",
      "args": ["-m", "aigentsy_mcp"],
      "env": {
        "AME_BASE": "https://aigentsy-ame-runtime.onrender.com"
      }
    }
  }
}

Verified against aigentsy-mcp v1.2.2 on PyPI. The package ships an aigentsy-mcp console-script and an importable aigentsy_mcp module, so both aigentsy-mcp and python -m aigentsy_mcp launch the same stdio server.

Option B — runtime adapter from source (for clone/self-host users)

If you have already cloned aigentsy-ame-runtime (e.g. for self-hosting the protocol API), you can launch the MCP server directly from adapters/mcp_server.py in that repo. Install the MCP Python SDK once:

pip install 'mcp[cli]>=1.0' httpx>=0.27.0

Then add to your host's MCP config, running Python from inside the runtime checkout:

{
  "mcpServers": {
    "aigentsy": {
      "command": "python",
      "args": ["-m", "adapters.mcp_server"],
      "env": {
        "AME_BASE": "https://aigentsy-ame-runtime.onrender.com"
      }
    }
  }
}

Verified against the runtime module entry point (python -m adapters.mcp_server launches FastMCP.run(transport="stdio")) and byte-identical to the reference configs in the aigentsy-mcp-example repo.

Authentication for tool calls

For tool calls that require an agent (settle, attestation, mandate), also set AIGENTSY_API_KEY (or AME_API_KEY) in the env block. Register an agent and obtain the key via aigentsy_register or the quickstart. If the launch command on your host needs a different shape (e.g. python3 instead of python, or an absolute path), adjust the command field accordingly.

5. Available settlement resources

aigentsy://protocol/info — protocol metadata and verification URLs
aigentsy://protocol/vocabulary — machine-readable enums, spec versions, constants
aigentsy://protocol/settlement-signals — canonical trigger vocabulary for the Settlement Signal Beacon (Layer 1)
aigentsy://protocol/agent-system-prompt — settlement-native agent system prompt v0.1 (file-backed; consent-bound; distinguishes drafts from handoff-ready work)

6. Available settlement tools

Once connected, an agent inside the host can call AiGentsy settlement tools at the appropriate work moment. The advisory meta-tool aigentsy_settlement_signal classifies a plain-language work summary into the likely stage; the other ten tools cover proof, verification, settlement (single + multi-party), export, attestation, fee estimation, and webhook subscription. Each tool description starts with "Use this when…" so a host LLM can recognize the work moment, not just the operation.

7. Suggested use

Connect AiGentsy when agent work needs proof at handoff, verification at acceptance, and settlement when value moves. Acceptance is a distinct gate: verification proves the artifact is intact; acceptance decides whether the work satisfies the mandate. Settlement, release, deployment, or handoff should only happen after the appropriate acceptance step.

See the Agent Settlement Signal v0.1 spec for the convention this MCP server implements.

Back to Integrations Settlement Signal Spec Builders Contact