Perses

You run a Perses MCP Server locally to enable LLM hosts to interact with the Perses Application through a standardized MCP interface. This lets tools like Claude Desktop or VS Code access Perses data and actions safely and consistently, whether you run the server on your machine or expose it over HTTP.

How to use

Connect your MCP client to the Perses MCP Server using either the STDIO (local) mode or the Streamable HTTP (remote) mode. In STDIO mode, you run the MCP server locally and connect via standard input/output from your client. In Streamable HTTP mode, you expose the MCP server over HTTP so multiple clients can connect from different machines. Ensure you have your Perses authentication token ready to authorize requests.

Before you start, obtain your token with the Perses CLI, then configure your MCP client to point at the MCP server URL or the local STDIO setup. Decide which transport fits your workflow: STDIO for tight, local integration or HTTP for remote, multi-client access.

How to install

Prerequisites you need: a Perses server, a local development environment, and the Percli tool. You will also need a Perses authentication token.

Step 1: Obtain your Perses authentication token. Open a terminal and log in to Perses with percli, then fetch your token.

percli login <PERSES_SERVER_URL>

percli whoami --show-token

Step 2: Prepare and run the MCP server in either STDIO or HTTP mode. The following examples come directly from common configurations you will use.

Configuration examples

STDIO mode configurations are used when you want a local, direct connection between the MCP server and your MCP client (Claude Desktop or VS Code). Copy the appropriate config into your environment and restart the client.

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--perses-server-url",
        "<PERSES_SERVER_URL>"
      ],
      "env": {
        "PERSES_TOKEN": "<PERSES_TOKEN>"
      }
    }
  }
}

HTTP streamable mode exposes the MCP server over HTTP so multiple clients can connect. Start the server with the HTTP transport and the Perses server URL you intend to connect to.

/path/to/mcp-server --transport streamable-http --perses-server-url <PERSES_SERVER_URL> --port 8000

If you are configuring an editor to connect via HTTP, you can point it to the HTTP endpoint you started.

{
  "servers": {
    "perses-http": {
      "type": "http",
      "url": "http://localhost:<port>/mcp"
    }
  }
}

Notes on security and maintenance

Keep your PERSES_TOKEN secret. If your token expires, regenerate or extend the token duration in Perses and update your MCP server configuration accordingly.

Read-only mode is available by adding a read-only flag to the server configuration. In read-only mode, only information-retrieving tools are available.

Available tools

perses_list_projects

List all projects available in Perses.

perses_get_project_by_name

Retrieve a project by its name.

perses_create_project

Create a new project with the given configuration.

perses_list_dashboards

List all dashboards for a specific project.

perses_get_dashboard_by_name

Get a dashboard by name within a project.

perses_create_dashboard

Create and configure a new dashboard for a project.

perses_list_global_datasources

List all global datasources.

perses_list_datasources

List all datasources for a specific project.

perses_get_global_datasource_by_name

Get a global datasource by name.

perses_get_project_datasource_by_name

Get a project datasource by name.

perses_create_global_datasource

Create a new global datasource.

perses_update_global_datasource

Update an existing global datasource.

perses_list_global_roles

List all global roles.

perses_get_global_role_by_name

Get a global role by name.

perses_list_global_role_bindings

List all global role bindings.

perses_get_global_role_binding_by_name

Get a global role binding by name.

perses_list_project_roles

List all roles for a specific project.

perses_get_project_role_by_name

Get a project role by name.

perses_list_project_role_bindings

List all role bindings for a project.

perses_get_project_role_binding_by_name

Get a project role binding by name.

perses_list_plugins

List all supported plugins.

perses_list_global_variables

List all global variables.

perses_get_global_variable_by_name

Get a global variable by name.

perses_list_variables

List all variables for a specific project.

perses_get_project_variable_by_name

Get a project variable by name.

perses_create_project_variable

Create a project-level variable.