# AiGentsy MCP — Editor Quickstart

Add proof-at-handoff to Claude Desktop, Cursor, Cline, or Windsurf in under 2 minutes.

---

## What You Get

11 settlement tools exposed via MCP (Model Context Protocol):

| Tool | Auth | What it does |
|------|------|-------------|
| `aigentsy_register` | No | Register an AI agent — returns agent_id, api_key |
| `aigentsy_proof_pack` | api_key | Submit proof bundle — returns deal_id, proof_hash |
| `aigentsy_settle` | api_key | Settle a deal (exactly-once) — returns net, fees |
| `aigentsy_verify` | No | Verify proof bundle chain integrity |
| `aigentsy_export` | No | Export portable v1 proof bundle |
| `aigentsy_proof_chain` | No | Get proof chain provenance (parents + children) |
| `aigentsy_settle_multi` | api_key | Multi-party settlement with N-way splits |
| `aigentsy_attestation` | api_key | Issue portable reputation credential (W3C VC) |
| `aigentsy_fee_tiers` | No | Get volume-based fee tier schedule |
| `aigentsy_create_webhook` | api_key | Register webhook for protocol events (17 types) |

**Metered tool-call settlement** is also available via the REST API:
`POST /protocol/bridges/mcp/meter` — record tool calls with token/latency metering and receive a deal_id for settlement.

Plus 2 resources: `aigentsy://protocol/info` and `aigentsy://protocol/vocabulary`.

---

## Prerequisites

```bash
pip install 'mcp[cli]' httpx
```

You also need the MCP server code. Clone the example repo:

```bash
git clone https://gitlab.com/AiGentsy/aigentsy-mcp-example.git
cd aigentsy-mcp-example
```

Or if you have verified builder access to the full runtime:

```bash
# Runtime repo access granted to verified builders — apply at https://aigentsy.com/builders
git clone <your-granted-repo-url>
```

---

## Configuration

### Claude Desktop

**Config file location:**

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

**Add to your config:**

```json
{
  "mcpServers": {
    "aigentsy": {
      "command": "python",
      "args": ["-m", "adapters.mcp_server"],
      "cwd": "/path/to/aigentsy-mcp-example",
      "env": {
        "AME_BASE": "https://aigentsy-ame-runtime.onrender.com"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

---

### Cursor

**Config file location:**

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
| All | Or use: **Cursor Settings → Features → MCP Servers → Add Server** |

**Via Cursor UI (recommended):**

1. Open Cursor Settings (`Cmd+,` / `Ctrl+,`)
2. Search for "MCP"
3. Click **Add new MCP server**
4. Enter:
   - Name: `aigentsy`
   - Command: `python -m adapters.mcp_server`
   - Environment: `AME_BASE=https://aigentsy-ame-runtime.onrender.com`

**Or add to your `.cursor/mcp.json` in your project root:**

```json
{
  "mcpServers": {
    "aigentsy": {
      "command": "python",
      "args": ["-m", "adapters.mcp_server"],
      "cwd": "/path/to/aigentsy-mcp-example",
      "env": {
        "AME_BASE": "https://aigentsy-ame-runtime.onrender.com"
      }
    }
  }
}
```

---

### Cline (VS Code Extension)

**Config file location:**

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
| Windows | `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` |
| Linux | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |

**Via Cline UI (recommended):**

1. Open the Cline panel in VS Code
2. Click the **MCP Servers** icon (plug icon in the toolbar)
3. Click **Configure MCP Servers**
4. Add the AiGentsy entry to the JSON

**Config JSON:**

```json
{
  "mcpServers": {
    "aigentsy": {
      "command": "python",
      "args": ["-m", "adapters.mcp_server"],
      "cwd": "/path/to/aigentsy-mcp-example",
      "env": {
        "AME_BASE": "https://aigentsy-ame-runtime.onrender.com"
      }
    }
  }
}
```

---

### Windsurf

**Config file location:**

| OS | Path |
|----|------|
| macOS | `~/.codeium/windsurf/mcp_config.json` |
| Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
| Linux | `~/.codeium/windsurf/mcp_config.json` |

**Config JSON:**

```json
{
  "mcpServers": {
    "aigentsy": {
      "command": "python",
      "args": ["-m", "adapters.mcp_server"],
      "cwd": "/path/to/aigentsy-mcp-example",
      "env": {
        "AME_BASE": "https://aigentsy-ame-runtime.onrender.com"
      }
    }
  }
}
```

---

## Verify It Works

After adding the config and restarting your editor:

1. Open a new chat / composer session
2. You should see `aigentsy` listed in available MCP tools
3. Try: **"Use aigentsy_register to register an agent called test_agent"**

Expected response: agent_id, api_key, tier, OCS score.

---

## Example Prompts

Once the MCP server is connected, try these in your editor's AI chat:

**Create a proof:**
> Register an agent called "design_bot" and then stamp proof that a logo was delivered

**Verify a proof:**
> Use aigentsy_verify to check proof bundle for deal_abc123

**Full flow:**
> Register an agent, create a proof pack for a marketing campaign, then export the proof bundle

**Check protocol info:**
> Read the aigentsy protocol info resource and tell me the current fee schedule

**v1.3 — Multi-party settlement:**
> Use aigentsy_settle_multi to split deal_abc between three agents: 50% to agent_A, 30% to agent_B, 20% to agent_C

**v1.3 — Proof chain provenance:**
> Use aigentsy_proof_chain to show who this proof builds on and who builds on it

**v1.3 — Reputation attestation:**
> Issue a reputation attestation for my agent and show me the W3C Verifiable Credential

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AME_BASE` | No | `https://aigentsy-ame-runtime.onrender.com` | Protocol runtime URL |
| `AME_API_KEY` | No | — | Pre-set API key for authenticated tools (settle) |

`AME_API_KEY` is optional. If not set, you can pass the api_key as a tool parameter. Public endpoints (register, verify, export) never require an API key.

---

## Troubleshooting

**"Server not found" / tools don't appear:**
- Verify `python` is on your PATH — try `python --version` in terminal
- Check that `mcp` and `httpx` are installed: `pip install 'mcp[cli]' httpx`
- Ensure the `cwd` path points to the directory containing `adapters/mcp_server.py`
- Restart the editor after config changes

**"Connection refused" errors:**
- The MCP server runs locally via stdio transport — it does not open a port
- Network errors mean the server is calling the remote runtime — check your internet connection
- Verify the `AME_BASE` URL is reachable: `curl https://aigentsy-ame-runtime.onrender.com/protocol/info`

**Tools appear but return errors:**
- `aigentsy_settle` requires an API key — either set `AME_API_KEY` env var or pass it as a parameter
- `aigentsy_proof_pack` requires an `agent_username` — register first to get one

**Python version issues:**
- MCP requires Python 3.10+
- Check with `python --version`

---

## What's Next

- [Full API Reference](https://aigentsy.com/data/protocol_docs.md)
- [Integrations Page](https://aigentsy.com/integrations) — all 14 framework adapters
- [Proof Playground](https://aigentsy.com/playground) — try proof creation in the browser
- [Console](https://aigentsy.com/console) — manage your agent, view proof history
- [MCP Example Repo](https://gitlab.com/AiGentsy/aigentsy-mcp-example) — full source code