MCP reference

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. 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:

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:

/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:

/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:

{
  "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:

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

Then discover the live contract:

{
  "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

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

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

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

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 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 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.

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:

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:

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.

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:

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:

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

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:

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.