Search API and MCP

Two ways to reach an indexed Proxyma instance from outside its own chat window: a plain HTTP search endpoint, and an MCP server your coding assistant can call directly.

Search API

One endpoint. It runs the same hybrid search the chat window uses - keyword and vector retrieval, fused and reranked - and returns the matching passages with their sources.

POST /api/v1/search

Request body

Basic request

curl -X POST https://your-proxyma-host/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication flow", "topK": 5}'

Authentication

Proxyma Desktop has no accounts and no authentication - the endpoint is open to anything that can reach the machine, which is why it binds to localhost.

Proxyma Server answers an unauthenticated call using shared resources only. Send an access token to scope the search to your own resources as well:

curl -X POST https://your-proxyma-host/api/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-access-token>" \
  -d '{"query": "authentication flow", "topK": 5}'

Create a token from Settings, under API access. A token carries the permissions of the account that issued it and nothing more - it can never read a resource that account cannot.

Response

{
  "results": [
    {
      "content": "The auth module handles JWT...",
      "source": "confluence://PROJ/auth-design",
      "score": 0.87
    }
  ]
}

MCP

Proxyma exposes a Model Context Protocol server, so an assistant that speaks MCP can search your indexed sources itself rather than being pasted excerpts. The endpoint is:

https://your-proxyma-host/mcp

On Server, MCP requires an access token and the client sees exactly what that account can see. On Desktop there are no accounts, so the configurations below need no Authorization header at all - drop that line.

Claude Code (CLI and VS Code extension)

Run this in a terminal. The VS Code extension bundles the same CLI, so this connects it too - the extension cannot add MCP servers directly, and the connection is managed 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, shareable through version control) or ~/.claude.json (per user, all your projects).

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

GitHub Copilot (VS Code)

Add to .vscode/mcp.json, or run MCP: Open User Configuration from the Command Palette for a configuration shared across workspaces. Note that the key is servers here, not mcpServers, and that "type": "http" is required for the same reason as above.

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

What a client can reach

Both interfaces are subject to the same rules as the web interface. An MCP client or API caller authenticated as you sees your resources and shared ones; an unauthenticated caller on Server sees shared resources only. Neither can reach another user's private resources, and neither exposes absolute filesystem paths - source references are returned as connector-scoped identifiers.