Skip to content

MCP

Jump to bottom
Dariusz Jarosz edited this page Aug 27, 2026 · 1 revision

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 sits beside the REST API over the same data — it does not replace it, and has no write tools.

Table of Contents

Connecting

claude mcp add --transport http bely https://<host>:8181/bely/api/mcp --header "token: <TOKEN>"

Anonymous connections (no --header) work too — see Authentication. Once connected, just ask the model things like "list the BELY logbook types" or "search BELY for beam dump".

To get a token, log in via the REST API; the token comes back as a response header, not in the body:

curl -X POST https://<host>:8181/bely/api/auth/login \
  -d 'username=<user>' -d 'password=<pass>' -D - -o /dev/null | grep -i '^token:'

Authentication

  • No token header → anonymous access, matching the existing anonymous REST read routes. All tools work.
  • token header present but invalid/expired → rejected (a token that was offered and rejected is a real error, not a silent downgrade to anonymous).
  • Set cdb.portal.mcp.requireAuth=true to lock the endpoint down for deployments that want mandatory auth.
  • No OAuth support. The MCP spec's HTTP auth profile expects OAuth 2.1, which this endpoint does not implement — Claude Desktop's "Add custom connector" OAuth flow will not authenticate against it. Use manual header injection (as above), or front the endpoint with an OAuth-aware reverse proxy for internet-facing deployments.

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.requireAuth false Requires a valid token header for every call when true.
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.
  • Protocol revision 2026-07-28 only (stateless Streamable HTTP, no SSE, no sessions). Legacy MCP clients that require an initialize handshake are not supported.

Clone this wiki locally