Norn MCP setup

Connect your AI assistant to Norn to read and act on your portfolios, brokerage accounts, and stock research directly from the assistant.

What this is

Norn ships an MCP (Model Context Protocol) server. This lets AI assistants — Claude Code, Claude Desktop, Cursor, and any other MCP-compatible client — access Norn on your behalf.

Once connected, you can ask your AI assistant things like:

• "Screen for large-cap tech stocks with a Sharpe ratio above 1.5."
• "What's the current allocation of my Roth IRA at Fidelity?"
• "Build a Black-Litterman optimized portfolio with these five tickers, assuming NVDA outperforms by 10%."
• "Save that portfolio to my Growth workspace."

Prerequisites

• A Norn account with an active Pro subscription. Account and portfolio tools require Pro.
• An MCP-compatible AI client. Below covers Claude Code and Claude Desktop.
• A modern web browser for the OAuth login step.

Endpoint reference

For automation or unusual clients. Most users can skip this — the walkthroughs below cover client-specific setup.

No API keys, no manual tokens — the "log in with Norn" browser flow does everything. Refresh tokens are handled by the client SDK.

Setup for Claude Code

Claude Code is Anthropic's terminal-based AI coding assistant.

1. Install Claude Code if you haven't already. Follow the instructions at docs.claude.com/en/docs/claude-code.

2. Add the Norn MCP server. Either method works — pick whichever you prefer.

   Option A — in-session /mcp command (recommended). Start Claude Code in any project directory and type:

   /mcp
   

   In the MCP management interface, choose "Add server" and enter:

   • Name: norn
   • URL: https://norn-data.com/mcp
   • Transport: HTTP (streamable)

   Option B — CLI command. From your shell:

   claude mcp add --transport http norn https://norn-data.com/mcp
   

3. Authenticate. Claude Code opens a browser window to Norn's login page the first time it needs the connection. Sign in with your Norn credentials and approve the requested scopes (mcp:read, mcp:write). The browser hands the session back to Claude Code automatically.

4. Verify. Type /mcp inside a session, or run claude mcp list in the shell. Norn should appear as connected.

5. Try it out. In a Claude Code session, ask:

   "Using the norn MCP server, list the organizations I'm a member of."

Config file reference

To commit the server config to a repo (so teammates get it automatically), add this to .mcp.json at your project root (or ~/.claude.json for a global config):

{
  "mcpServers": {
    "norn": {
      "type": "http",
      "url": "https://norn-data.com/mcp"
    }
  }
}

OAuth still runs through the browser on first use — the config file just tells Claude Code where the server lives.

Setup for Claude Desktop

Claude Desktop is Anthropic's Mac / Windows desktop app.

Note: Claude Desktop's built-in "Connectors" panel lists Anthropic-approved MCP servers from the Software Directory. Norn is applying for that directory — once approved, connection will be one click. Until then, connect Norn as a custom connector.

Option A — Connectors UI (recommended)

Requires a recent Claude Desktop version.

1. Open Claude Desktop → Settings → Connectors.
2. Click "Add Custom Connector" (button wording varies between releases — look for "Custom", "Add server", or a + icon in the Connectors area).
3. Enter:
   • Name: Norn
   • URL: https://norn-data.com/mcp
   • Transport: HTTP (streamable)
4. Claude Desktop opens a browser window to Norn's login page. Sign in with your Norn credentials and approve the mcp:read and mcp:write scopes.
5. Once the browser redirects back, Norn appears in the Connectors panel as Connected.
6. Start a new Claude conversation and ask: "List my Norn organizations."

Option B — Config file with mcp-remote (fallback for older Claude Desktop)

Older Claude Desktop builds don't have the Connectors UI and speak MCP over stdio only. To connect to Norn's remote HTTP server from those versions, use the mcp-remote proxy — a small npx-run process that bridges stdio to Norn's HTTP endpoint and handles the OAuth handshake.

1. Install Node.js (v18 or newer) if you don't already have it. mcp-remote runs via npx.

2. Edit Claude Desktop's config file.

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

   Add the norn entry inside mcpServers:

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

   If you already have other MCP servers configured, add the norn key alongside them — don't overwrite the file.

3. Fully quit and reopen Claude Desktop so it picks up the config.

4. The first time Claude Desktop uses the server, mcp-remote opens a browser window to Norn's login page. Sign in with your Norn credentials and approve the requested scopes. Subsequent starts reuse the stored session.

5. In a new Claude conversation, ask: "List my Norn organizations."

Which option should you use? If your Claude Desktop has a "Connectors" tab in Settings, use Option A — it's simpler and doesn't require Node.js. Only fall back to Option B if the Connectors UI is missing or your version can't add custom connectors.

What Norn can see when connected

When you connect an MCP client, the client can call read tools without prompting you (it's your client, on your machine). Read tools cover:

• Your organizations and workspaces
• Your saved portfolios and their computed weights
• Your brokerage accounts, positions, and transaction history
• Norn's full stock database (screening, correlations, quant summaries)

Write tools (create / edit / delete saved portfolios) require the client to have obtained the mcp:write scope during login. If you skipped it, you can re-authenticate to grant it.

Norn does not read anything from your AI client's memory, chat history, or uploaded files. The connection is one-way: your client reads and writes Norn state; Norn does not read the client's state.

Troubleshooting

• "Authentication failed" or 401 errors: Sign out of Norn in your browser and re-authenticate through the MCP client.
• "Permission denied: organization X (Pro+ required)": The organization you're targeting is on a lower tier. Upgrade in the Norn web app.
• Tools show up but always return empty: Verify you're passing an organization_id you're actually a member of. Call list_organizations first.
• Everything else: Email support@nornhq.com.