MCP access from other AI clients

Polaris has a built-in Model Context Protocol (MCP) server. Connect an AI client such as Claude Code, Cursor or Codex to it, and that client can ask Polaris questions about your data, run SQL against your project, and work with stories, without leaving the client.

Chats started over MCP are saved in Polaris, so you can open them in the web app later.

Find your endpoint URL

1. In Polaris, go to Settings › Integrations & MCP and open the Polaris MCP tab.
2. Copy the MCP Endpoint URL. It looks like this:

https://epigenomics.polaris.aws.grail.com/mcp/<project-id>

The same page has step-by-step guides for each client, with your URL already filled in. If Enable MCP endpoint is off, ask an admin to turn it on.

Connect a client

Most clients sign in through your browser with OAuth. You approve the client once in Polaris, and it gets its own access token.

Claude Code

Add the server, then sign in:

claude mcp add --transport http Polaris https://epigenomics.polaris.aws.grail.com/mcp/<project-id>

Start Claude Code, run /mcp, select Polaris and choose to authenticate. Your browser opens Polaris to approve the connection.

Cursor

Open Settings › Tools & MCP, select New MCP Server, and paste this JSON, or put it in .cursor/mcp.json:

{
  "mcpServers": {
    "Polaris": {
      "type": "http",
      "url": "https://epigenomics.polaris.aws.grail.com/mcp/<project-id>"
    }
  }
}

Sign in when Cursor asks.

Codex

Open Settings › MCP servers › Add server › Streamable HTTP, paste the endpoint URL, save, and sign in when asked.

Other clients

The Polaris MCP page also has guides for Claude Desktop (Settings › Connectors › Add custom connector), ChatGPT (developer mode apps), GitHub Copilot in VS Code (.vscode/mcp.json) and Dust.

Use a token instead of OAuth

For a client that cannot do OAuth, the Polaris MCP page shows a config with an Authorization: Bearer header and your token filled in. That token is your current web session, so it stops working when you sign out or the session ends. Prefer OAuth when the client supports it. Never commit the token to Git.

What the client can do

Tool	What it does
ask_pda	Asks Polaris a question. Polaris runs its full agent and returns the answer, queries and stories. This is the tool clients should use first.
get_pda_answer	Checks on a long answer that ask_pda reported as still running.
ls_pda_context, grep_pda_context, read_pda_context	List, search and read the project context files.
execute_sql	Runs a read-only SQL query against the project’s databases.
execute_semantic_query	Queries the semantic layer, when the project has one.
display_chart, display_map	Draws a chart or map and returns a link to view it.
list_stories, get_story, create_story, update_story	Works with stories. Creating stories needs the Stories feature for your group.
archive_story, delete_story	Archives a story, or deletes it permanently.

Admins also get tools to search and read chat history across the project.

Example prompt in Claude Code:

Ask Polaris which genes are most often mutated in TCGA-BLCA, then summarize the top five for me.

Who can connect

Admins, users and context admins can connect. Viewers cannot. Clients act as you and see only what you can see in Polaris.

For admins

On the Polaris MCP page, admins can:

• Turn the endpoint on or off with Enable MCP endpoint.
• See Connected apps, the OAuth clients that have connected.
• Read Recent MCP calls, the last 50 calls from external clients.
• Choose the model that ask_pda uses.