Glossary MCP Server

Business Glossary knowledge-graph search, hosted as a private, single-tenant Keboola MCP data app. Claude (or any MCP client) calls this directly instead of going through the Streamlit testing UI.

Built from the mcp-data-app skill's Keboola-MCP template, swapped to wrap our own tools instead of the full Keboola MCP server (see the two # ── SWAP POINT comments in server.py / pyproject.toml).

Tools

Tool	Input	Returns
search	query, top_k=5	Cosine-ranked glossary terms: {score, term, type}
expand	term, depth=1	Terms connected in the concept graph, any relation, direction-aware
trace_inputs	term	Formula dependency chain (core_isReferencing edges only)
resolve_physical	term	Physical Keboola table/column names implementing the term
ask	question	Full pipeline: split into concepts, resolve each with related terms, suggest a next step

No live Keboola connection at runtime — data/*.csv + data/embeddings.parquet (same export used by glossary-search-app-azure) load once at import time. Only search/ask call OpenAI (to embed the incoming query); expand/ trace_inputs/resolve_physical are pure local lookups.

Local development

pip install -e .
export MCP_API_KEY=$(openssl rand -hex 32)
export OPENAI_API_KEY=sk-...
python server.py

curl http://localhost:5000/healthz
curl -i http://localhost:5000/mcp   # expect 401 without a bearer token

Deploy to Keboola

1. Push this repo to the data app's git remote (pick one driver — kbagent, hosted MCP modify_python_js_data_app + create_python_js_data_app_git_credential, or manual UI — see the mcp-data-app skill's reference/deploy.md).
2. Set secrets:
   • #OPENAI_API_KEY
   • #MCP_API_KEY (openssl rand -hex 32)
3. Set App-level auth to None (critical — Keboola's OIDC strips the Authorization header otherwise; MCP_API_KEY is the real security boundary). Set auto-suspend ≥ 24h.
4. Deploy. Copy the resulting app URL.
5. Set #MCP_PUBLIC_URL to that URL, redeploy (two-pass — the OAuth-shape discovery docs need to advertise the real origin).
6. Verify:

   curl -sS https://<app-url>/healthz
   curl -sS https://<app-url>/.well-known/oauth-protected-resource
   curl -sS -i https://<app-url>/mcp   # expect 401 + WWW-Authenticate
   

Connect from Claude

• Bearer: any MCP client that supports a static Authorization: Bearer <MCP_API_KEY> header.
• claude.ai / Claude Desktop "Add custom connector": point it at https://<app-url>/mcp; the OAuth-shape stubs (/register, /authorize, /token) let its GUI flow complete, gated by client_secret == MCP_API_KEY.

Re-exporting data

Same source tables as glossary-search-app-azure — see that project's README for the export SQL and the CSV→parquet conversion for embeddings.parquet. Redeploy after replacing data/*.