MCP Server

Logchef serves a Model Context Protocol endpoint at <public_url>/mcp. AI assistants use it to query logs, read schemas, run LogchefQL, and inspect alerts. There is no separate process to install. The endpoint is part of the Logchef server.

https://logchef.example.com/mcp

The endpoint uses the Streamable HTTP transport in stateless mode. It accepts POST requests and returns JSON. GET and DELETE return 405. A request body can be up to 1 MiB.

Authentication

The endpoint accepts Logchef OAuth access tokens and nothing else. The MCP client runs the OAuth flow:

1. The client sends you to the Logchef consent page in your browser.
2. You sign in to Logchef (SSO or local login) and review the request.
3. You choose Approve or Deny.
4. The client receives a short-lived access token (10 minutes) and a refresh token (30 days).

The consent page shows the client name, the address the browser returns to, and the exact scopes. For a client that identifies itself with a URL, it also shows “Published by” and the host of that URL. Approve only a connection that you started yourself.

These credentials get 401 at /mcp:

• API tokens, including service tokens.
• Browser session cookies.
• OAuth tokens issued for the CLI. Those tokens work only for /api.

An OAuth token for /mcp gets 401 at /api. The two are separate audiences.

To revoke an assistant, open Settings → Connected apps in the Logchef web UI and remove it. The next request from that assistant fails.

Note

The endpoint exists only when an operator has enabled OAuth. Without it, /mcp and unknown /.well-known/* paths return 404. Refer to Logchef OAuth for the server settings.

Connect a client

Each client has its own setup steps. Refer to Agent Setup for Claude Code, Codex, Cursor, Claude.ai, Claude Desktop, and ChatGPT.

What an assistant can see

An assistant acts with your identity and sees only what you can see.

• Read-only. Every tool reads data. No tool changes teams, sources, users, tokens, saved queries, or alerts.
• Seven read scopes. The consent page requests profile:read, teams:read, sources:read, logs:read, saved_queries:read, collections:read, and alerts:read. It can also request offline_access, which lets the client refresh the token without asking you again. Tools that need a scope the token does not hold do not appear in the tool list.
• Team membership only. An OAuth token sees the teams you belong to and the sources linked to those teams. This applies to admins too. An admin’s web session can open any team, but an admin’s agent token cannot.
• Same limits as the web UI. One MCP tool call ends after query.mcp_call_timeout_seconds (default 60, never more than query.max_timeout_seconds). Concurrency limits follow query.max_concurrent_per_user and query.max_concurrent_global.

Caution

Logs are untrusted text. A log line can contain instructions aimed at an assistant. Review what an assistant does with log content, and keep the assistants you connect to the minimum that you need.

Available tools

Profile and metadata

Tool	Description
get_profile	The profile for this connection: a stable id, plus name and email when known
get_teams	Teams you belong to, with your role and member counts
get_meta	Server version and configuration details

Sources

Tool	Description
get_sources	All sources you can access, across your teams
get_team_sources	Sources that belong to one team
get_source_schema	Columns and types, or discovered fields, for a source

Querying logs

Tool	Description
query_logs	Run a source-native query: SQL for ClickHouse, LogsQL for VictoriaLogs
get_log_histogram	Log volume over time, with optional grouping
get_log_context	Log entries before and after a timestamp

LogchefQL

Tool	Description
query_logchefql	Run a LogchefQL query
translate_logchefql	Translate LogchefQL to the source’s native language without running it
validate_logchefql	Check LogchefQL syntax without running it

Investigation and analysis

Tool	Description
get_field_values	Top distinct values for one field in a time range
get_all_field_dimensions	Top values for all low-cardinality fields in one call
top_values	Top values for several fields in one call (up to 20 fields)
compare_windows	Run the same LogchefQL filter in two time windows and compare the samples
open_investigation	Open the investigation panel

Saved queries and alerts

Tool	Description
list_saved_queries	Saved queries you can see, optionally for one source
get_saved_query	One saved query by ID
list_alerts	Alert rules for a source
get_alert_history	Evaluation history for one alert

The alert tools return an error when alerting is disabled on the server.

Not included

These capabilities are not part of the endpoint:

• Administration. There are no tools to manage teams, users, sources, or API tokens.
• Writes. There are no tools to create, change, or delete saved queries, collections, or alerts.
• AI query generation. The assistant that you connect writes the query. Logchef’s own AI SQL assistant is part of the web UI only.
• Query telemetry. There is no tool for ClickHouse system.query_log.

Resources

Resources give an assistant read-only data without a tool call.

URI template	Description
logchef://team/{team_id}/source/{source_id}/schema	Schema for a source
logchef://source/{source_id}/saved-queries	Saved queries for a source
logchef://saved-query/{query_id}	One saved query

Prompts

Two prompts guide an investigation.

Prompt	Arguments	Description
investigate_error_spike	team_id and source_id (required), time_range (optional, default last hour)	Schema discovery, error volume, patterns, timeline, and root cause
investigate_alert	alert_id (required), team_id and source_id (optional)	Alert configuration, history, matching logs, and a summary

Investigation panel

open_investigation opens an interactive panel inside the conversation, using MCP Apps. In the panel you can:

• Browse your sources.
• Run bounded LogchefQL queries and read the results.
• Select a histogram interval or log rows.
• Compare two time windows.
• Attach the evidence you selected to the conversation.

The panel runs the requested query when it opens. If the assistant calls open_investigation again while the panel is open, the panel replaces its source, filter and time range with the new request, clears the previous selection and attached evidence, and runs the new query. The panel shows inline or in full screen, depending on the client. A client that does not support MCP Apps still gets the tool result as text.

The panel is one self-contained page. It has no access to external networks. It calls the same read-only tools as the assistant, with the same token.

Next steps

• Set up your client: Agent Setup
• Enable the endpoint on your server: Logchef OAuth
• Prefer a terminal workflow? See the Logchef CLI