Documentation

Connecting to PolarisRay

PolarisRay serves each dataset as a remote MCP server over HTTP. Any MCP-capable client or agent framework connects the same way — point it at the endpoint URL. Public sources need no API key.

Endpoints

Every live source lives under a path on mcp.polarisray.com, and each path is the MCP endpoint — pass it as-is, no suffix:

• https://mcp.polarisray.com/federated
• https://mcp.polarisray.com/maude
• https://mcp.polarisray.com/faers
• https://mcp.polarisray.com/recalls
• https://mcp.polarisray.com/clinical_trials
• https://mcp.polarisray.com/dailymed
• https://mcp.polarisray.com/spl
• https://mcp.polarisray.com/chembl
• https://mcp.polarisray.com/pubchem
• https://mcp.polarisray.com/pdb

Transport is Streamable HTTP (clients that only speak SSE fall back automatically). Browse the catalog for tools, examples, and disclaimers. /federated searches MAUDE, FAERS, ClinicalTrials.gov, DailyMed, openFDA SPL, FDA recalls, ChEMBL, and PubChem in one call. Each is also available on its own path; PDB (RCSB protein structures) is standalone only — not part of /federated.

One-click add

Add any source to Claude, Cursor, or ChatGPT in a click — no config file needed:

Add to Claude opens Claude's “Add custom connector” dialog with the name and URL filled in — just click Connect (works on the web and desktop app; Free, Pro, Max, Team, Enterprise). Add to Cursor opens Cursor's install prompt and writes the server into mcp.json (Cursor must be installed on the machine). Add to ChatGPT copies the endpoint to your clipboard and opens ChatGPT — paste it into Settings → Connectors → Add custom MCP server (requires a paid plan with developer/MCP access; OpenAI has no prefill link yet).

Sourced results

Search and get tools return a url when a public detail page exists — DailyMed and openFDA drug labels, ClinicalTrials.gov studies, FDA MAUDE device reports, and FDA iRES recall records — so you can open the primary source. FAERS is different: FDA does not publish a per-case web page, so hits link to the quarterly extract, not an individual case.

Set up your client

Pick your client below. Each example wires up a single source (maude); add the others as more entries under the same object, swapping the path. The federated endpoint is the easiest way to get most sources behind one connection (everything except PDB).

Claude Code

Add it from the CLI:

claude mcp add --transport http polarisray-maude https://mcp.polarisray.com/maude

…or drop it in .mcp.json (project) / your user config:

{
  "mcpServers": {
    "polarisray-maude": {
      "type": "http",
      "url": "https://mcp.polarisray.com/maude"
    },
    "polarisray-faers": {
      "type": "http",
      "url": "https://mcp.polarisray.com/faers"
    },
    "polarisray-federated": {
      "type": "http",
      "url": "https://mcp.polarisray.com/federated"
    }
  }
}

Claude Desktop

Remote servers are added through the UI, not the config file: Settings → Connectors → Add custom connector, give it a name, and paste an endpoint URL (e.g. https://mcp.polarisray.com/maude). Then click Connect. Available on Free, Pro, Max, Team, and Enterprise plans (Team/Enterprise members may need an admin to add it org-wide first).

If you prefer the claude_desktop_config.json file, bridge the remote server with mcp-remote:

{
  "mcpServers": {
    "polarisray-maude": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.polarisray.com/maude"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project), then enable the server in Settings → MCP:

{
  "mcpServers": {
    "polarisray-maude": {
      "url": "https://mcp.polarisray.com/maude"
    }
  }
}

VS Code (Copilot agent mode)

Requires VS Code 1.102+ with GitHub Copilot. Add to .vscode/mcp.json (workspace) or your user mcp.json — note the top-level key is servers and remote entries use "type": "http":

{
  "servers": {
    "polarisray-maude": {
      "type": "http",
      "url": "https://mcp.polarisray.com/maude"
    }
  }
}

Windsurf

Open Cascade → MCP → Configure (~/.codeium/windsurf/mcp_config.json). Windsurf uses serverUrl for remote servers — not url — and you must click Refresh after editing:

{
  "mcpServers": {
    "polarisray-maude": {
      "serverUrl": "https://mcp.polarisray.com/maude"
    }
  }
}

Other MCP clients

Cline, Goose, Zed, LibreChat, and anything else that speaks remote MCP work the same way — supply the endpoint URL. If a client offers both “URL/HTTP” and “command/stdio” server types, choose the URL/HTTP option.

Agent frameworks & SDKs

Building your own agent? Connect PolarisRay as a tool source and hand the discovered tools to your model loop.

Python MCP SDK

The reference client, directly over Streamable HTTP:

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client("https://mcp.polarisray.com/maude") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()      # resolve, search_reports, get_report, ...
        hits = await session.call_tool(
            "search_reports", {"query": "infusion pump battery failure", "size": 5}
        )

OpenAI Agents SDK

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    params={"url": "https://mcp.polarisray.com/maude"}
) as maude:
    agent = Agent(
        name="FDA analyst",
        instructions="Use the MAUDE tools to answer device-safety questions.",
        mcp_servers=[maude],
    )
    result = await Runner.run(agent, "Recent infusion-pump device problems?")
    print(result.final_output)

LangChain / LangGraph

Via langchain-mcp-adapters, which adapts MCP tools into LangChain tools:

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "maude": {"url": "https://mcp.polarisray.com/maude", "transport": "streamable_http"},
    "federated": {"url": "https://mcp.polarisray.com/federated", "transport": "streamable_http"},
})
tools = await client.get_tools()   # hand these to a LangGraph / LangChain agent

Authentication

Public datasets are open and require no credentials. Sources that wrap rate-limited or licensed data will document an api-key flow on their individual pages; pass it as a request header in whichever client field above accepts headers (e.g. headers in Windsurf/VS Code, or mcp-remote --header for Claude Desktop).