First Tool Call

NEXUS's local MCP server, nexus-mcp, speaks newline-delimited JSON-RPC 2.0 over stdio: one message per line, no embedded newlines. The examples on this page are formatted across multiple lines for readability — on the wire, each is exactly one line. Field values that are illustrative rather than part of the contract (cache lifetimes, version strings) are marked as such; the field names and error codes are the real contract.

nexus-mcp supports two protocol versions: 2026-07-28 (current) and 2025-06-18 (legacy). Which one a client uses determines whether it needs an initialize handshake at all.

Modern clients (2026-07-28)

There is no initialize handshake in this version. Every request instead carries a _meta block naming the protocol version, and normally the calling client's identity and capabilities:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {},
  "_meta": {
    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
    "io.modelcontextprotocol/clientInfo": {
      "name": "example-cli",
      "version": "1.0.0"
    },
    "io.modelcontextprotocol/clientCapabilities": {}
  }
}

server/discover is mandatory for a 2026-07-28 session — it is how a client learns what this server offers before calling anything else:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "supportedVersions": ["2026-07-28", "2025-06-18"],
    "capabilities": {
      "toolNamespaces": ["canvas", "agent"]
    },
    "resultType": "server/discover",
    "ttlMs": 60000,
    "cacheScope": "session",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "nexus-mcp"
      }
    }
  }
}

Every result on this server carries resultType; results that return lists — like this one — also carry ttlMs and cacheScope, telling the caller how long the result is safe to treat as current and how broadly it may be reused. Treat ttlMs and cacheScope's exact values above as illustrative — read them from your own response rather than assuming these numbers. The tool names inside toolNamespaces are enumerated in the MCP tools reference, not repeated here.

If the version is unsupported

A request whose _meta names a version outside supportedVersions is rejected immediately, without touching the rest of params:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "server/discover",
  "params": {},
  "_meta": {
    "io.modelcontextprotocol/protocolVersion": "2024-01-01"
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32022,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2026-07-28", "2025-06-18"],
      "requested": "2024-01-01"
    }
  }
}

data.supported and data.requested are always present on this error, so a client can decide whether to retry on an older version it also speaks.

Legacy clients (2025-06-18)

A client built against the classic MCP handshake does not need any of the above — the standard initialize method still works unchanged:

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "nexus-mcp"
    }
  }
}

A 2025-06-18 session does not gain the server/discover result envelope (resultType, ttlMs, cacheScope) — those fields belong to the current version. Everything else a client already knows about the classic handshake and about tools/call applies unchanged.

Next

Both eras reach the same two tool namespaces from here. Continue to Draw a diagram from an agent to make your first tool call inside a real session, or read the MCP protocol reference for the full contract.

This is also the last page of the Getting Started path — see Where to go next for a map of everything else this documentation covers.