mcp

The Perses MCP Server exposes a standard MCP interface that allows LLM hosts and editors to interact with the Perses application using either STDIO or streamable HTTP transports. This enables tools like Claude Desktop, VS Code Copilot, or other MCP-enabled clients to discover and operate Perses resources such as dashboards, projects, datasources, and variables. To get started, provide your Perses authentication token via the PERSES_TOKEN environment variable and configure the transport you’ll use (stdio for local, http for remote). The server supports registering specific resources with the --resources flag for finer control or leaving it empty to register all available resources. When using HTTP mode, you’ll typically run the server on a port (default 8000) and point clients to http://<host>:8000. In STDIO mode, the MCP server communicates directly with the host process through standard input and output, suitable for desktop integrations like Claude or VS Code where a binary can be wired into the host’s I/O streams.

Prerequisites:

• Access to the Perses Perses server and a valid PERSES_TOKEN obtained via percli
• The Perses MCP Server binary released for your OS/architecture (from the releases page)

Installation steps:

1. Download the MCP Server binary for your OS from the releases page: https://github.com/perses/mcp-server/releases
2. Make the binary executable (UNIX-like systems):

chmod +x /path/to/perses-mcp-server

3. Place the binary somewhere in your PATH or reference the absolute path when configuring mcp_config.
4. Prepare a Perses server URL (the backend Perses instance) you will connect to, and obtain a PERSES_TOKEN via the percli login workflow:

percli login <PERSES_SERVER_URL>
percli whoami --show-token

5. Create or edit your MCP client configuration to point to the MCP Server binary (see mcp_config in this document). For STDIO, ensure the host process wires the MCP binary’s STDIN/STDOUT; for HTTP, start the server with the appropriate transport and port.

Tip: If you need to load a YAML-based configuration, supply --config /path/to/config.yaml; enable file logging with --log.file-path /path/to/logfile.log.

Environment variables and tips:

• PERSES_TOKEN is required for authentication with the Perses backend.
• PERSES_TOKEN may expire; if your token expires, re-authenticate with percli and update the token value.
• When using STDIO mode, the MCP client (host) is responsible for providing input and handling output; ensure your host application is compatible with the MCP protocol version used by the server.
• When using HTTP mode, ensure the port you choose is open and not blocked by firewalls, and consider using TLS in production.
• Resources: you can limit which resources are registered via --resources (e.g., dashboard, project, datasource, variable, plugin). If omitted, all resources are registered by default.
• If you intend read-only operations only, add --read-only to the transport arguments.
• Logs: use --log.file-path to capture logs to a file; otherwise logs go to stderr.