# MCP reference

> The canonical Agreebase MCP contract for transport, authentication, structured workflows, verification, signing, and guarded lifecycle actions.

Audiences: developers, agents
Kind: reference
Updated: 2026-07-17

This is the canonical public reference for Agreebase's Model Context Protocol (MCP) server. It describes the operating contract an agent should follow, not just a list of function names.

For a first connection, start with the [MCP quickstart](/docs/developers/mcp-quickstart). For the current exact schemas, enums, annotations, and output models of discoverable tools, call `tools/list` on the connected server. The live discovery response is authoritative for that focused catalogue. Advanced lifecycle tools documented below remain directly callable by exact name even when omitted from discovery.

Agreebase creates permanent, tamper-evident records. It is not a legal service. An agent must preserve user-provided facts, avoid inventing signatures or approvals, show exact text before recording it, and stop for human inputs and consequential confirmations.

## Operating model

An MCP client normally performs this sequence:

```text
initialize → notifications/initialized → tools/list → tools/call
```

The server returns structured workflow state so the agent can continue without guessing. A response may contain:

- `next_action`: the exact next tool and arguments suggested by Agreebase.
- `human_step`: a user-facing prompt, proof text, URL, title, challenge, or expiry that must be handled outside the tool call.
- `requires_confirmation`: whether the agent must obtain explicit approval.
- `error_code`: a machine-readable failure category.
- `required_scopes`: the exact permission needed for a protected action.
- `retry_action`: a safe, structured recovery operation.

Treat these fields as the workflow protocol. Do not derive a tool name from a free-form message when `next_action.tool` is available.

## Transport contract

The hosted connector endpoint is:

```text
/mcp/oauth
```

It is the endpoint for ChatGPT and Claude custom remote MCP connectors. It requires an OAuth access token before MCP initialization and exposes protected resource metadata at `/.well-known/oauth-protected-resource/mcp/oauth`. Authorization-server metadata is at `/.well-known/oauth-authorization-server`; dynamic registration, authorization, token, and revocation are at `/register`, `/authorize`, `/token`, and `/revoke`.

The direct/raw endpoint is:

```text
/mcp
```

Both endpoints delegate to the same FastMCP application, tool registry, schemas, annotations, and domain handlers. `/mcp` retains public verification, API-key bearer transport, and short-lived MCP session authentication. It uses streamable HTTP. A raw client must:

1. `POST` JSON-RPC to `/mcp` with `Content-Type: application/json`.
2. Advertise `Accept: application/json, text/event-stream`.
3. Save the `Mcp-Session-Id` response header from `initialize`.
4. Send subsequent requests with that session header.
5. Accept either an SSE `message` event or a JSON response body.

The initialization request must identify the client and offer a supported MCP protocol version. The server's negotiated `protocolVersion` is authoritative:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-agent",
      "version": "1.0.0"
    }
  }
}
```

After receiving the initialization result, send:

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized",
  "params": {}
}
```

Then discover the live contract:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

The discovery response includes each tool's `inputSchema`, `outputSchema`, description, and `annotations`. The `annotations` are safety metadata, not a replacement for authorization. In particular, a `readOnlyHint` does not grant access, and a `destructiveHint` does not by itself mean that the tool is forbidden.

## Tool catalog

### Public and authentication tools

| Tools | Access | Purpose |
|---|---|---|
| `verify_agreement` | Public on `/mcp`; OAuth transport required on `/mcp/oauth` | Return a certificate or compare supplied text, hashes, or a transaction. |
| `get_authentication_status` | Public | Report current transport/session authentication and scopes. |
| `request_authentication_otp` | Public | Email a short-lived authentication code. This has an external side effect. |
| `verify_authentication_otp` | Public | Bind the user-provided authentication code to the current MCP session. |

Authentication OTP access is limited to the `retrieve` scope. It is not a signature OTP and does not grant `create`, `verify`, `amend`, or `cancel`.

### Creation tools

| Tool | Scope | Purpose |
|---|---|---|
| `create_agreement` | `create` | Create a multi-party agreement draft and start the initiator workflow. |
| `create_declaration` | `create` | Create a personal declaration or attestation draft. |
| `create_notarization` | `create` | Record a file, text, or supplied SHA-256 content identity. |

Creation records the supplied content. The agent must obtain human review of the exact final text and publication settings before calling a creation tool.

### Signature execution tools

| Tool | Scope | Purpose |
|---|---|---|
| `start_or_resume_signature_execution` | `verify` | Start or resume the current participant's session. |
| `get_signature_execution` | `verify` | Read the current participant's signature state. |
| `start_signature_method` | `verify` | Start one method for the current record version. |
| `submit_signature_method_input` | `verify` | Submit an OTP, public URL, or passkey payload. |
| `refresh_signature_method` | `verify` | Refresh an asynchronous proof or challenge. |
| `cancel_signature_method` | `verify` | Cancel a pending method. |
| `finalize_signature_execution` | `verify` | Finalize after the required methods are satisfied and the human confirms. |

Supported signature methods are `email_otp`, `github_gist`, `x_post`, `reddit_post`, `webauthn_passkey`, `telegram`, and `api_key` where the live schema makes that method available. The response identifies which methods are available for the current participant and record.

### Retrieval and verification tools

| Tool | Scope | Purpose |
|---|---|---|
| `get_agreement` | `retrieve` | Read an authenticated record and permitted participant evidence. |
| `list_agreements` | `retrieve` | List records in the authenticated identity graph. |
| `get_agreement_card` | `retrieve` | Retrieve a sealed record card as a single-use URL, native MCP image, or explicit compatibility base64. |
| `verify_agreement` | Public | Verify a reference or compare a supplied artifact without private signer evidence. |

`get_agreement` and `list_agreements` are identity-graph operations. Public verification deliberately does not disclose private signer evidence.

### Image and share-card representations

Image-bearing reads default to compact metadata. [Identicon](/docs/concepts/identicons) metadata contains `kind`, `digest`, `short_hash`, `width`, `height`, `alt_text`, and `available`; it does not contain `algorithm`, `version`, SVG bytes, or a data URI. Share-card metadata contains artifact metadata only and never an internal storage path.

`get_agreement`, `list_agreements`, and `verify_agreement` expose `visual_representation` with `metadata`, `inline`, and `compatibility_data_uri` values. `metadata` is the safe default. `inline` adds MCP-native `ImageContent` while keeping image bytes out of structured content. `compatibility_data_uri` is an intentional legacy mode. MCP `structuredContent` and `content[0].text` are the same redacted JSON payload; native inline bytes are separate content blocks.

`list_agreements` and public `verify_agreement` return or inline document identicons only. Authenticated `get_agreement` can additionally return current party signature-identicon metadata and images, while authenticated signature execution tools expose the current caller's finalized signature identicon.

`get_agreement_card` exposes `representation`:

- `url` (default) issues a five-minute, scoped, single-use ticket URL;
- `inline` returns native MCP PNG content without structured image bytes;
- `compatibility_base64` returns legacy base64 bytes in structured content.

Card issuance requires the existing authenticated participant authorization for the declarant, signer, co-signer, or witness. An already-authenticated MCP session is reused; no second authentication step is required. A ticket URL contains no agreement reference, uses `APP_BASE_URL`, and is redeemed atomically exactly once after successful artifact retrieval. Redeemed and expired ticket rows are removed by an hourly maintenance job. See the dedicated [image-handling guide](/docs/developers/image-handling) for visibility and local-versus-hosted URL behavior.

### Guarded lifecycle tools

Every pair below has a read-only preview followed by a separate execute call. The execute call requires the matching short-lived confirmation token and the expected agreement version.

| Preview / execute pair | Scope | Effect |
|---|---|---|
| `preview_amend_agreement` / `amend_agreement` | `amend` | Create a new version from an existing agreement. |
| `preview_update_agreement_draft` / `update_agreement_draft` | `amend` | Change a draft before it is sealed. |
| `preview_resend_participant_invitation` / `resend_participant_invitation` | `amend` | Queue an invitation resend. |
| `preview_replace_declined_witness` / `replace_declined_witness` | `amend` | Replace a declined witness. |
| `preview_resolve_counter_proposal` / `resolve_counter_proposal` | `amend` | Accept, partially accept, or reject a counter-proposal. |
| `preview_withdraw_counter_proposal` / `withdraw_counter_proposal` | `amend` | Withdraw the proposer's pending counter-proposal. |
| `preview_remove_party` / `remove_party` | `cancel` | Remove a participant and affect pending work. |
| `preview_submit_counter_proposal` / `submit_counter_proposal` | `amend` | Submit a counter-proposal and move the record into counter review. |
| `preview_waive_declined_witness` / `waive_declined_witness` | `cancel` | Waive a declined witness when the state permits it. |
| `preview_waive_declined_co_notarizer` / `waive_declined_co_notarizer` | `cancel` | Complete without one declined co-notarizer; other invitations remain active. |
| `preview_rescind_agreement` / `rescind_agreement` | `cancel` | Rescind a pending agreement, declaration, or notarization. |
| `preview_cancel_draft` / `cancel_draft` | `cancel` | Cancel an unsealed draft. |
| `preview_decline_agreement` / `decline_agreement` | `cancel` | Decline participation in the current version. |

The advanced amendment, decline, witness/co-notarizer exception, and
counter-proposal pairs are omitted from `tools/list` to keep initial discovery
focused. They remain registered and directly callable by the exact names shown
above, with the same authentication, scope, role/state, preview, and confirmation
requirements.

## Authentication and scopes

ChatGPT and Claude hosted connectors authenticate at `/mcp/oauth` with the standard authorization-code flow, PKCE S256, Dynamic Client Registration, and resource binding. The authorization ceremony is passwordless:

```text
Connect → enter email → enter OTP → Verify and connect
```

The authorization page displays the requesting client, exact registered redirect origin, permissions, and 90-day connection duration. The user always submits the OTP through **Verify and connect**; an existing browser session is not silently reused. The OAuth grant contains `create`, `retrieve`, `verify`, `amend`, `cancel`, and `offline_access`. Access tokens last one hour. Refresh tokens rotate and remain bounded by the original 90-day grant expiry. Rotation replay revokes the token family. Revocation invalidates the family and its active access tokens.

The direct `/mcp` endpoint resolves authentication from the request transport. A request may carry:

```http
Authorization: Bearer <Agreebase API key or short-lived MCP transport token>
```

The direct endpoint also binds a successful MCP authentication OTP to the current session. The short-lived manual transport token returned when a client cannot preserve session state is valid for at most 600 seconds and is transport-only. Do not store it in long-term memory, prompts, notes, or logs.

Use `get_authentication_status` before protected work. If the response is not authenticated, a protected tool returns a structured `auth_required` error with the exact `required_scopes`. If the credential is valid but too narrow, the tool returns `missing_scope` with both `required_scopes` and `available_scopes`.

| Scope | MCP operations |
|---|---|
| `create` | Creation tools. |
| `retrieve` | `get_agreement`, `list_agreements`, and `get_agreement_card`. |
| `verify` | Signature execution and the authenticated participant actions around it. |
| `amend` | Amendments, draft updates, invitation resends, witness replacement, and counter actions. |
| `cancel` | Participant removal, witness waiver, rescission, draft cancellation, and decline. |

The direct MCP authentication OTP bootstrap grants `retrieve` only. It is suitable for listing and reading records, not for creating or signing them. Use a permitted transport API key or token with the exact required scope for those workflows. MCP never accepts an API key as a normal tool argument.

On `/mcp/oauth`, `get_authentication_status` reports `auth_method="oauth"` and the OAuth principal. The three bootstrap tools remain in the shared schema for direct-client compatibility and are unnecessary for hosted connectors. An OAuth token is accepted only at `/mcp/oauth`; an API key is accepted only by the direct transport. Agents must never ask a user to provide an API key through a prompt or tool call.

Authentication and signing remain strictly separate. An `authenticate` OTP can never become signature evidence, satisfy a required signature method, enable `can_finalize`, or finalize a record. Signature intent always requires the separate record/version-specific `signature_email_otp` or another configured signature method. OAuth authentication does not activate the API-key signature method and cannot use notarization `auto_seal`.

## Creation contract

### Agreements and declarations

`create_agreement` and `create_declaration` require the agent to supply the complete final `body`, participant identity fields, and explicit blockchain publication booleans. The live schema defines all optional fields, but the important creation rules are:

- Bodies are limited to 350 normalized words and 7,000 characters.
- Agreements have at most 15 total signing participants, including the initiator.
- There may be at most five active witnesses.
- `witness_names` must have exactly one name for every `witnesses` address.
- `required_signature_method_count` is `1`, `2`, or `3`.
- `on_chain_full_text` publishes the final sealed text rather than only hashes and metadata.
- `on_chain_include_verified_parties` makes verified signer or witness details public in on-chain metadata and may require an additional human acknowledgement.

Creation returns an agreement summary, signature state, and usually a `next_action`. The creation response is not proof that the record is sealed.

### Notarizations

`create_notarization` accepts `content_type` of `file`, `text`, or `hash` and a SHA-256 `content_hash` in the form `sha256:<64 lowercase hexadecimal digits>`.

- Hash a file's exact bytes on the client; do not send file bytes or local file paths as ordinary notarization content.
- For text notarizations, provide the text and ensure its normalized hash is the supplied `content_hash`.
- File and hash notarizations require a `label` or `filename`.
- `text_public` controls whether normalized text may appear in public reads.
- At most fourteen co-notarizers may be supplied.
- `signature_mode="auto_seal"` is an explicit API-key flow and requires the conditions advertised by the live schema, including one required signature method.

Notarization metadata records what Agreebase intentionally did not ingest. It does not turn an uploaded file into a signed PDF.

## Signature execution contract

Signature execution is scoped to a participant and an agreement version. A successful signature response contains `signature_execution`, whose important fields are:

- `agreement_version`: the version being signed.
- `required_count` and `completed_count`: method progress.
- `minimum_satisfied`: whether the required method count is met.
- `can_finalize`: whether finalization is currently permitted.
- `finalization_blocker`: why finalization is not yet possible.
- `methods`: method-specific status and human instructions.
- `public_party_details_acknowledgement_required`: whether finalization needs explicit acknowledgement of public participant details.

Method-specific inputs are deliberately not interchangeable:

| Method | Start or submit input |
|---|---|
| `email_otp` | Agreebase's six-digit signature code, not an authentication code. |
| `github_gist`, `x_post`, `reddit_post` | The exact generated proof text and then the resulting public URL. |
| `telegram` | The generated challenge or Telegram flow returned by Agreebase. |
| `webauthn_passkey` | A browser-native passkey ceremony and returned payload. |
| `api_key` | Only when the live schema and current workflow make it available. |

Do not paraphrase proof text or Reddit titles. Do not ask a user to paste a private key. When `human_step` is present, stop and give the user the requested instruction rather than attempting to complete it autonomously.

## Verification contract

`verify_agreement` is public and takes:

| Argument | Use |
|---|---|
| `agr_reference` | Required record reference. |
| `body` | Exact candidate agreement or declaration text. |
| `body_hash` | Hash of the candidate agreement body. |
| `content_hash` | Hash of notarized content. |
| `document_hash` | Hash of a signed or rendered document. |
| `tx_hash` | Blockchain transaction hash; requests a live chain check. |

Supply the strongest artifact available. A reference-only call returns a certificate. It does not compare a document.

| `verdict` | Meaning |
|---|---|
| `verified` | A submitted artifact matched and the record is sealed/current as required. |
| `certificate` | The current record was found, but no artifact was submitted. |
| `matched_superseded` | An artifact matched an older record that is no longer current authority. |
| `matched_not_sealed` | An artifact matched, but the record is not sealed. |
| `no_match` | The record exists but the submitted artifact did not match. |
| `not_found` | No record matched the supplied reference. |

The response also reports per-check fields under `checks`, the selected `match_method`, blockchain status, `on_chain_check`, and compact document identicon metadata when a sealed record exists. A visual identicon is a secondary cryptographic fingerprint; it never replaces hashes, sealed status, signature state, or `verify_agreement`.

## Guarded lifecycle contract

A lifecycle preview is read-only but may expose the consequences of an action:

- `actor_identity_summary` identifies the authenticated actor.
- `target_summary` identifies the affected record, participant, witness, or counter-proposal.
- `current_status` and `agreement_version` identify the state being previewed.
- `consequences` describes state and participant effects.
- `notifications_queued` describes expected notifications.
- `sealing_or_blockchain_effect` describes permanence or chain effects.
- `confirmation_token` and `expires_at` authorize the matching execute call.

The execute call must use the same authenticated principal, scope, AGR reference, target identifiers, and expected agreement version. A missing, expired, stale, wrong-principal, wrong-scope, wrong-target, or wrong-version request is not permission to proceed. Follow `retry_action` back to the correct preview tool.

## Response and error handling

When a tool executes, prefer the MCP `structuredContent` object. It follows the tool's `outputSchema`. The text content block is a human-readable JSON copy and is useful as a fallback for clients that do not expose structured content.

There are two error layers:

1. The MCP dispatcher may reject an unknown tool or invalid arguments. The JSON-RPC result may have `isError: true`; re-read `tools/list` and correct the call.
2. A tool may execute and return `success: false`, `error_code`, `error`, and recovery fields. Handle this as a workflow result, not as a transport retry.

Common structured errors:

| Error | Agent response |
|---|---|
| `auth_required` | Obtain the required transport/session authentication. |
| `invalid_credentials` | Stop and reconnect with a valid credential. |
| `missing_scope` | Tell the user the exact missing scope and request an appropriately permitted connection. |
| `validation_error` | Correct the arguments against the current input schema. |
| `confirmation_required` | Call the matching preview tool before executing. |
| `stale_confirmation_token` | Refresh the preview; do not reuse the old token. |
| `expired` | Restart the expired human or lifecycle step. |
| `forbidden` | Stop; do not probe alternate principals or targets. |
| `conflict` | Read the current state and follow the returned retry action. |
| `rate_limited` | Wait for `retry_after_seconds` and avoid a tight retry loop. |
| `not_found` | Report that the record or target was not found without inventing a result. |

Do not log bearer tokens, refresh tokens, authorization codes, client secrets, OAuth transaction identifiers, API keys, OTP codes, confirmation tokens, proof payloads, or private participant evidence.

## Privacy, permanence, and limits

Agreebase records durable evidence. Before creation or finalization, explain:

- Hash-only chain publication exposes a digest and metadata rather than full text.
- Full-text chain publication is more public and permanent.
- Verified party details may publish names and signing contact details when explicitly enabled and acknowledged.
- Public verification does not reveal private signer evidence.
- Notarization stores the supplied content identity and whitelisted metadata; it does not need source file bytes.

The principal limits are:

- Agreement and declaration body: 350 normalized words and 7,000 characters.
- Agreement participants: 15 total signing participants.
- Active witnesses: five.
- Notarization co-notarizers: fourteen.
- OAuth access token: one hour.
- OAuth connection: fixed 90 days from consent.
- Manual MCP authentication transport token: at most 600 seconds.

When a limit or enum is important to a call, trust the current `tools/list` schema over copied documentation.