MCP

BELY MCP Endpoint

BELY exposes a Model Context Protocol endpoint at /api/mcp, letting an LLM client (Claude Code, Claude Desktop) search and read the logbook directly, without a sidecar process or the generated API client. It implements server/discover, tools/list, and tools/call (see Limitations for protocol revision support). It sits beside the REST API over the same data — it does not replace it.

The endpoint is read-only and unauthenticated: no token, header, or OAuth flow is needed.

Table of Contents

• Connecting
• Configuration
• Available Tools
• Limitations

Connecting

claude mcp add --transport http bely https://<host>:8181/bely/api/mcp

Once connected, just ask the model things like "list the BELY logbook types" or "search BELY for beam dump".

Configuration

Set in cdb.portal.properties:

Property	Default	Description
cdb.portal.mcp.enabled	true	Disables the endpoint (404) when set to false.
cdb.portal.mcp.allowedOrigins	(empty)	Comma-separated list of allowed Origin header values for browser-based clients. Non-browser clients (Claude Code/Desktop) don't send Origin and are unaffected.

Available Tools

Tool	Purpose
bely_search	Search log documents and entries by text, with logbook type/system/user/date filters.
bely_list_log_documents	List log documents of a given logbook type, newest first.
bely_get_log_document	Fetch a document's header plus its section list, by id or name.
bely_list_log_entries	Page through entries in a document or section, bodies truncated.
bely_get_log_entry	Fetch one entry in full, with attachments, replies, and reactions.
bely_list_lookups	List logbook types, systems, or document templates.
bely_list_users	List/search users, e.g. to resolve a user id for bely_search.
bely_list_user_groups	List/search user groups.

All results are hand-rendered, size-capped text (not raw entity JSON) with "showing N of M" footers and follow-up hints — tune expectations accordingly if you're inspecting responses directly.

Limitations

• Read-only: no create/update/attach tools are exposed over MCP. Use the REST API or the UI for writes.
• Only data available to anonymous readers is exposed; there is no way to authenticate for additional access over MCP.
• Dual-era Streamable HTTP: modern clients using per-request metadata (protocol revision 2026-07-28, including the server/discover method) are served statelessly. Clients that speak an earlier revision (2025-03-26 through 2025-11-25) are served via a sessionless initialize handshake instead — no Mcp-Session-Id is issued or required, since none of BELY's tools carry per-connection state. Either way there's no SSE stream and no server-initiated messages; GET/DELETE on the endpoint both return 405.