MCP Setup Guide

This guide covers creating a Proxima service account and configuring LLM clients to connect to the MCP server.

Prerequisites

• A running Proxima MCP server (see Configuration for deployment)
• A Proxima Console user account with admin access (to create service accounts)

Step 1: Create a Service Account

Service accounts provide API keys for programmatic access. Each service account is scoped to specific clients and permissions.

1. Log in to Proxima Console at https://app-console.prxm.uz
2. Navigate to Admin > Service Accounts
3. Click Create Service Account
4. Configure:
   • Name: e.g. mcp-claude-desktop
   • Role: select a read-only role (read-only access is sufficient for all MCP tools)
   • Client scope: Select which clients this account can access, or leave empty for all
5. Copy the generated API key — it will only be shown once

API Key Security

Store the API key securely. Never commit it to version control. The MCP server only logs the first 10 characters of API keys for debugging purposes.

Step 2: Configure Your LLM Client

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Streamable HTTP (recommended)

{
  "mcpServers": {
    "proxima": {
      "url": "https://mcp-console.prxm.uz/mcp",
      "headers": {
        "Authorization": "Bearer prxm_your_api_key_here"
      }
    }
  }
}

stdio (local binary)

If running the MCP server locally as a binary:

{
  "mcpServers": {
    "proxima": {
      "command": "/path/to/proxima-mcp",
      "env": {
        "PROXIMA_API_URL": "https://api-console.prxm.uz",
        "PROXIMA_API_KEY": "prxm_your_api_key_here",
        "PROXIMA_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project root or global settings):

{
  "mcpServers": {
    "proxima": {
      "url": "https://mcp-console.prxm.uz/mcp",
      "headers": {
        "Authorization": "Bearer prxm_your_api_key_here"
      }
    }
  }
}

Claude Code

Add to your Claude Code MCP settings (.claude/settings.json or project-level .mcp.json):

{
  "mcpServers": {
    "proxima": {
      "url": "https://mcp-console.prxm.uz/mcp",
      "headers": {
        "Authorization": "Bearer prxm_your_api_key_here"
      }
    }
  }
}

Or using stdio with a local binary:

{
  "mcpServers": {
    "proxima": {
      "command": "/path/to/proxima-mcp",
      "env": {
        "PROXIMA_API_URL": "https://api-console.prxm.uz",
        "PROXIMA_API_KEY": "prxm_your_api_key_here",
        "PROXIMA_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Step 3: Verify the Connection

After configuring your client, test the connection by asking the AI assistant a question that triggers a tool call:

"List all online hosts"

The assistant should use the query_hosts tool and return a table of your infrastructure hosts.

If you encounter issues:

1. "Invalid or expired API key" — verify your service account API key is correct
2. "No API key provided" — check the Authorization header is set in your client config
3. Connection refused — verify the MCP server is running and reachable at the configured URL
4. "You don't have access to this resource" — check the service account's client scope and role permissions

Transport Comparison

Feature	Streamable HTTP	stdio
Authentication	Authorization header	PROXIMA_API_KEY env var
Network	Remote (HTTPS)	Local only
Multiple users	Yes (per-request auth)	No (single API key)
Health check	GET /healthz	N/A
Prometheus metrics	GET /metrics	N/A
Best for	Shared servers, production	Local development, CLI