Developers
Sign in Get started

Guide · MCP

Ardyn → your MCP server.

Ardyn lists a server’s tools without calling them. You enable the tools you want; Ardyn calls a selected tool with validated arguments and records a signed receipt. To connect an assistant to Ardyn instead, see ACTA MCP.

Supported profile

TransportStreamable HTTP (POST); responses as application/json or a single-message text/event-stream; Mcp-Session-Id honoured
Protocol versions2025-06-18 (offered), 2025-03-26 (accepted). Any other negotiated version is refused.
Discoveryinitialize, notifications/initialized, tools/list with nextCursor paging (≤ 20 pages, ≤ 500 tools)
CredentialsBearer token or a named header, stored as a handle; never forwarded anywhere else; Ardyn sign-in tokens are never sent
Tested withA previously unlisted server built on the official MCP Python SDK (1.26), over a real local transport — 28 of 28 cases

Not supported (visible limits)

  • stdio servers on a hosted runtime — needs a runtime you run next to the server
  • Server-initiated requests: sampling, elicitation, roots
  • Resource subscriptions and progress streams
  • Resources and prompts as capabilities (listed by the server, not exposed as operations)

Steps

  1. 1 · Register the server

    POST /v1/connections
{"family": "mcp", "name": "Field Notes",
 "config": {"endpoint": "https://mcp.example.com/mcp"},
 "credential": {"kind": "bearer", "value": "<server token>"}}

    The endpoint host is pinned to the connection. Private, loopback and metadata addresses are refused unless your runtime runs on that network.

  2. 2 · Discover (nothing is called)

    POST /v1/connections/<id>/discover
    {"tools": 3, "invoked": false, "protocol": "2025-06-18",
 "capability_ids": ["mcp:789ed47c/read_note@a772a882e107", …]}

    Capability ids include the connection and a digest of the tool’s contract, so two servers offering the same tool name never collide. Tool descriptions and hints are shown to you but never change permissions.

  3. 3 · Enable and classify

    POST /v1/capabilities/<url-encoded id>/enable  {"effect_class": "read"}

    A server’s readOnlyHint is not trusted. You decide read or write when enabling.

  4. 4 · Invoke

    POST /v1/capabilities/<url-encoded id>/invoke  {"arguments": {"note_id": "n-1"}}

    Arguments are validated against the pinned input schema first. Ardyn re-lists tools and refuses if the contract changed since you enabled it.

  5. 5 · Receipt

    The receipt holds the request as sent (credentials excluded), the server’s result, and any gaps. Export it with GET /v1/receipts/<id>/export and check it on /verify or with ardyn-verify.

Explicit non-success

Not enabled / superseded403 capability_not_enabled; nothing sent
Schema changed409 descriptor_changed; re-discover to get a new capability id for review
Invalid arguments400 invalid_arguments, with the schema path
Revoked409 connection_revoked; nothing sent
Tool error / malformed replyOperation failed; the receipt records TOOL_RESULT_MISSING and verifies as PARTIALLY SUPPORTED, never as success
Timeout after sendingOperation outcome_unknown