Claude Code Skills

MCP Server

Technical reference for Notery's MCP server endpoint and protocol.

Endpoint

POST/api/mcp

Model Context Protocol (MCP) server for AI tool integrations.

The MCP server is a single HTTP endpoint that implements the Model Context Protocol using JSON-RPC 2.0 over HTTP. All AI tool interactions — initialization, tool discovery, search, and retrieval — go through this endpoint.

Authentication

Every request must include an API key in the Authorization header:

Authorization: Bearer ntry_your_key_here

The API key determines which workspace the tools operate on. See API Keys for how to create and manage keys.

Protocol

The server implements MCP protocol version 2025-03-26 with the following methods:

Method	Description
`initialize`	Handshake — returns server info and capabilities
`notifications/initialized`	Client acknowledgment (returns 202)
`ping`	Health check
`tools/list`	Returns available tools (`notery_search`, `notery_get`)
`tools/call`	Invokes a tool with arguments

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "clientInfo": { "name": "your-client", "version": "1.0.0" }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "notery", "version": "1.0.0" },
    "instructions": "Notery MCP server provides search and document retrieval for your documentation workspace."
  }
}

Tool Call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "notery_search",
    "arguments": { "query": "authentication flow", "limit": 5 }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Found 3 results for: authentication flow\n..." }]
  }
}

Available Tools

The server exposes two tools via tools/list:

notery_search

Semantic search across workspace documents.

Parameter	Type	Required	Description
`query`	string	Yes	Natural language search query
`limit`	number	No	Max results (default 10, max 50)

See notery-search for full details.

notery_get

Fetch complete document content by ID.

Parameter	Type	Required	Description
`id`	string	Yes	Document UUID from search results

See notery-get for full details.

Error Handling

The server returns standard JSON-RPC 2.0 errors:

Code	Meaning
`-32600`	Invalid JSON-RPC request (malformed body)
`-32601`	Method not found (unsupported MCP method)

Tool-level errors (e.g., missing required parameter, document not found) are returned inside the tools/call response with isError: true:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "Error: query parameter is required" }],
    "isError": true
  }
}

You don't need to interact with the MCP protocol directly. Your AI tool handles the protocol automatically — just configure the endpoint URL and API key as described in Installation.