MCP setup

Connect an assistant that supports the Model Context Protocol to Proxyma so it can search your indexed sources.

Looking for the HTTP endpoints?

See the HTTP API reference for search, asking a question and streaming the answer, managing and syncing sources, uploading documents, tokens and instance information.

Replace the host in every example

Examples use https://your-proxyma-host. For Proxyma Desktop use http://localhost:4246; for the Home Server and Proxyma Enterprise Server use the address of its web interface.

MCP

The MCP endpoint is:

https://your-proxyma-host/mcp

On Enterprise Server, MCP requires an access token, and the client sees exactly what that account can see. On Desktop there are no accounts - leave out the Authorization header, AUTH_HEADER and --bearer-token-env-var in the configurations below.

Settings > AI Assistants in Proxyma shows each configuration below except Cursor's with your own address already filled in, ready to copy.

The Home Server has no accounts either, so MCP never asks for a token. Once PROXYMA_ALLOWED_HOSTS opens it beyond the machine itself, it answers /mcp only when PROXYMA_EXPOSE_MCP=true - and then anyone who can reach it can use the agent's tools, including those that write to Jira, Confluence and Bitbucket.

Claude Code (CLI and VS Code extension)

Run this in a terminal. It also connects the VS Code extension, which cannot add MCP servers itself; manage the connection afterwards with /mcp in the chat panel.

claude mcp add --transport http proxyma https://your-proxyma-host/mcp \
  --header "Authorization: Bearer <your-access-token>"

Or add it by hand to .mcp.json (per project) or ~/.claude.json (per user, all projects).

The "type" field is required

Without "type": "http", the entry fails to connect, and the error does not mention the missing field.

{
  "mcpServers": {
    "proxyma": {
      "type": "http",
      "url": "https://your-proxyma-host/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

Claude Desktop

Claude Desktop reaches an HTTP server through the mcp-remote bridge, which needs Node.js 18 or later. Open Settings > Developer > Edit Config in Claude, add the entry below, then quit Claude completely and open it again. For an http:// address such as Desktop's, add "--allow-http" after the address in args.

{
  "mcpServers": {
    "proxyma": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-proxyma-host/mcp",
               "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <your-access-token>" }
    }
  }
}

The token travels in env because Claude Desktop on Windows does not escape spaces inside args.

ChatGPT and Codex

The ChatGPT desktop app, the Codex CLI and the Codex extension for VS Code share one setting, so one command connects all three. Install the Codex CLI and sign in with your ChatGPT account, then run:

codex mcp add proxyma --url https://your-proxyma-host/mcp --bearer-token-env-var PROXYMA_TOKEN

Set the environment variable PROXYMA_TOKEN to your access token. ChatGPT on the web cannot reach a server on your own computer.

Gemini CLI

gemini mcp add -s user --transport http --header "Authorization: Bearer <your-access-token>" proxyma https://your-proxyma-host/mcp

Or add it to ~/.gemini/settings.json by hand. The field is httpUrl; url means an SSE server and does not connect.

{
  "mcpServers": {
    "proxyma": {
      "httpUrl": "https://your-proxyma-host/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

GitHub Copilot (VS Code)

Add this to .vscode/mcp.json, or run MCP: Open User Configuration from the Command Palette for all workspaces. The key is servers, not mcpServers, and "type": "http" is required.

{
  "servers": {
    "proxyma": {
      "type": "http",
      "url": "https://your-proxyma-host/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json for all projects, or to .cursor/mcp.json in a project.

{
  "mcpServers": {
    "proxyma": {
      "url": "https://your-proxyma-host/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

What a client can reach

MCP clients and API callers follow the same rules as the web interface. Authenticated as you, they see your connectors and shared ones. On Enterprise Server, MCP refuses a client without a token; without one, API search and chat see shared connectors only, and the source endpoints return 401. Neither can reach another user's private connectors.

With Write on for a connector, an MCP client can change that system through the agent's tools, and nobody is asked to approve the change.