← MDO Docs

Generic preview

This is a generic version of this article — vendor-specific item codes (Datastream, Worldscope, FactSet, and others) are shown as [VENDOR SPECIFIC ITEM CODE] placeholders.

Connecting Surge over MCP

Concept Overview

Surge exposes its tools through Snowflake-managed MCP servers. Model Context Protocol is the open standard that AI coding tools use to call external tools, so any MCP-capable assistant can be pointed at Surge — this page covers Claude Code, Codex, and GitHub Copilot.

The payoff is that your coding assistant stops guessing. Instead of inventing an item code that looks right, it calls catalog_search, gets the real code back, and writes mdosnow code that runs the first time. With mdosnow installed in the same environment, it can run that code too.

Every client uses the same underlying mechanism, so the setup is the same shape in all three cases:

  1. Generate a Programmatic Access Token (PAT) in Snowsight.
  2. Point the client at one or two Snowflake MCP server URLs, bridged through mcp-remote over stdio.
  3. Give the assistant the mdosnow SDK reference so it knows the function conventions.

Snowflake’s MCP endpoints advertise OAuth metadata. Configuring them as plain HTTP URLs makes most clients start an OAuth flow that will not complete against this setup. That is why every configuration below runs mcp-remote as a local stdio proxy and passes the PAT as a static Authorization header instead.

Back to Top

Prerequisites

From your Snowflake administrator, collect four things:

ItemExample
Snowflake account identifiermyorg-myaccount
MDO SDK app nameMDOSDK
MDO Surge app nameSURGE or MDO_SURGE
Latest mdosnow wheelmdosnow-<version>-py3-none-any.whl

On your own machine:

  • Node.js v18 or newer — required for the npx MCP bridge. Verify with node --version.
  • Python 3.11 (3.9–3.13 supported) with a virtual environment where mdosnow is installed, if you want your assistant to run the code it writes.
  • A Snowflake user with PAT authentication enabled — your admin configures this at the account level.

If the Surge admin installation has not been completed in your account, stop here — the steps below will connect but every tool call will fail. See What MDO Surge Is for what the admin setup creates.

Back to Top

Step 1: Generate a Snowflake PAT

The MCP servers authenticate with a Programmatic Access Token tied to your Snowflake user.

  1. In Snowsight, click your user icon (bottom-left) → Profile.
  2. Open the Authentication tab.
  3. Under Programmatic access tokens, click Generate token.
  4. Name it something descriptive, such as claude-code-mcp.
  5. Set an expiration that matches your organization’s policy — 90 days is common.
  6. Click Generate, then copy the token immediately. Snowflake shows the value once and never again.

If the Generate token button is missing, PAT authentication is not yet enabled for your account. Contact your Snowflake administrator.

A PAT is a credential. Treat it like a password: never commit it to version control, and add any file containing it to .gitignore.

Back to Top

Step 2: Know the Two URLs

There are two MCP servers, and they live in different Snowflake apps:

Server nameToolsURL path
mdo-catalogcatalog_search, security_search.../databases/<MDO-SDK-app>/schemas/APP_AI_API/mcp-servers/MDO_CATALOG_MCP_SERVER
mdo-surgeask_mdo_surge.../databases/<Surge-app>/schemas/APP_AI_API/mcp-servers/MDO_SURGE_MCP_SERVER

Both sit under https://<your-snowflake-account>.snowflakecomputing.com/api/v2/. Configure both for full functionality.

Swapping the two app names is the single most common setup mistake. The mdo-catalog URL must contain your MDO SDK app name, and the mdo-surge URL must contain your Surge app name. Get it backwards and the URL still looks valid, but the MCP server does not exist and the bridge fails with 404.

Back to Top

Step 3a: Claude Code

Claude Code reads MCP configuration from a .mcp.json file in the directory you launch it from. Create it in your project root.

Windows:

{
    "mcpServers": {
        "mdo-catalog": {
            "type": "stdio",
            "command": "cmd",
            "args": [
                "/c", "npx", "-y", "mcp-remote",
                "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-mdo-sdk-app>/schemas/APP_AI_API/mcp-servers/MDO_CATALOG_MCP_SERVER",
                "--header", "Authorization: Bearer <your-snowflake-PAT>"
            ],
            "env": {}
        },
        "mdo-surge": {
            "type": "stdio",
            "command": "cmd",
            "args": [
                "/c", "npx", "-y", "mcp-remote",
                "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-surge-app>/schemas/APP_AI_API/mcp-servers/MDO_SURGE_MCP_SERVER",
                "--header", "Authorization: Bearer <your-snowflake-PAT>"
            ],
            "env": {}
        }
    }
}

macOS / Linux: the same JSON, but change "command": "cmd" to "command": "npx" and drop the leading "/c" from args:

"args": [
    "-y", "mcp-remote",
    "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-mdo-sdk-app>/schemas/APP_AI_API/mcp-servers/MDO_CATALOG_MCP_SERVER",
    "--header", "Authorization: Bearer <your-snowflake-PAT>"
]

Then add the file to .gitignore so the PAT is never committed:

# .gitignore
.mcp.json

Start Claude Code from that directory and type /mcp. Both mdo-catalog and mdo-surge should be listed as connected.

Back to Top

Step 3b: Codex

Codex reads MCP configuration from ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows), using an mcp_servers table per server.

macOS / Linux:

[mcp_servers.mdo-catalog]
command = "npx"
args = [
    "-y", "mcp-remote",
    "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-mdo-sdk-app>/schemas/APP_AI_API/mcp-servers/MDO_CATALOG_MCP_SERVER",
    "--header", "Authorization: Bearer <your-snowflake-PAT>"
]

[mcp_servers.mdo-surge]
command = "npx"
args = [
    "-y", "mcp-remote",
    "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-surge-app>/schemas/APP_AI_API/mcp-servers/MDO_SURGE_MCP_SERVER",
    "--header", "Authorization: Bearer <your-snowflake-PAT>"
]

Windows: wrap the call in cmd so npx resolves, exactly as in the Claude Code configuration:

[mcp_servers.mdo-surge]
command = "cmd"
args = [
    "/c", "npx", "-y", "mcp-remote",
    "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-surge-app>/schemas/APP_AI_API/mcp-servers/MDO_SURGE_MCP_SERVER",
    "--header", "Authorization: Bearer <your-snowflake-PAT>"
]

You can also register a server from the command line instead of editing the file, which writes the same table for you:

codex mcp add mdo-surge -- npx -y mcp-remote "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-surge-app>/schemas/APP_AI_API/mcp-servers/MDO_SURGE_MCP_SERVER" --header "Authorization: Bearer <your-snowflake-PAT>"

Because config.toml lives in your home directory rather than the repository, the PAT is outside version control by default. Keep it that way — do not copy the config into a project.

Back to Top

Step 3c: GitHub Copilot

Copilot’s configuration file depends on the editor.

PyCharm and other JetBrains IDEs

The config file lives at:

C:\Users\<your-username>\AppData\Local\github-copilot\intellij\mcp.json

You can also reach it from the IDE: click the GitHub Copilot icon in the Chat panel, then Edit Settings → Model Context Protocol → Edit Config.

Note the top-level key is servers, not mcpServers:

{
  "servers": {
    "mdo-catalog": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y", "mcp-remote",
        "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-mdo-sdk-app>/schemas/APP_AI_API/mcp-servers/MDO_CATALOG_MCP_SERVER",
        "--header", "Authorization: Bearer <your-snowflake-PAT>"
      ]
    },
    "mdo-surge": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y", "mcp-remote",
        "https://<your-snowflake-account>.snowflakecomputing.com/api/v2/databases/<your-surge-app>/schemas/APP_AI_API/mcp-servers/MDO_SURGE_MCP_SERVER",
        "--header", "Authorization: Bearer <your-snowflake-PAT>"
      ]
    }
  }
}

Save the file, then open the GitHub Copilot MCP Log panel at the bottom of the IDE and click Start next to mdo-surge. Confirm the log shows no errors.

If an OAuth dialog appears (Add Client Registration Details), the config is still in HTTP form. Replace any url / requestInit entry with the command / args form above.

Finally, open Copilot Chat and switch to Agent mode from the dropdown at the bottom — MCP tools are not available in Ask mode.

VS Code

Create .vscode/mcp.json in your workspace, using the same servers key and the same command / args entries shown above for JetBrains. Add the file to .gitignore, since it will contain your PAT.

Manage the servers from the Command Palette with MCP: List Servers, and confirm the tools appear in Copilot Chat’s Agent mode.

Back to Top

Step 4: Give the Assistant SDK Context

The MCP tools tell your assistant which items exist. They do not teach it the mdosnow function conventions — that universes are modified in place, that _A and _Q items go through FundamentalData rather than PlugData, that universe.show() takes no arguments.

MDO publishes an SDK reference for exactly this purpose. Ask your MDO representative for the current MDOSDK.md, place it in your project root, and point your assistant at it:

  • Claude Code — add a line to CLAUDE.md:

    Before writing any mdosnow code, read MDOSDK.md for SDK reference and rules.
  • Codex — add the same instruction to AGENTS.md.

  • GitHub Copilot — add it to .github/copilot-instructions.md.

Keep MDOSDK.md as its own file rather than pasting it into your instructions file. MDO updates it independently, and keeping it separate means you can swap in a new version cleanly.

While you are there, tell the assistant which Python environment to use so it can run the code it writes:

- Python virtual environment: C:\Users\<your-username>\python_envs\mdosnow-env\Scripts
  - Use this environment when executing any mdosnow code

Back to Top

Step 5: Verify the Setup

Run these four checks in order. Each one exercises a different tool, so a failure tells you which server is misconfigured.

1. Item lookup (catalog_search):

Use the catalog_search tool to find the Datastream item code for closing price.

Expected: [VENDOR SPECIFIC ITEM CODE].

2. Security lookup (security_search):

Use the security_search tool to find the Datastream security code for Toyota.

Expected: a Security dimension value such as 676230-JP.

3. Documentation lookup (ask_mdo_surge):

Use the ask_mdo_surge tool to show me an example of using FundamentalData.

Expected: a code snippet from the documentation.

4. End-to-end code generation:

Write mdosnow code to get S&P 500 monthly constituents for the last 3 years
with closing prices and market cap in USD.

Expected: working code built on ConstituentUniverse and PlugData, with a real constituent item code that the assistant looked up rather than invented.

When all four pass, you are done. If mdosnow is installed in the environment you pointed the assistant at, it can now run the code it generates as well as write it.

Back to Top

Tips

  • Keep responses concise. Prefix Surge questions with [CONCISE]. Responses come back much shorter and cost far fewer tokens, which matters because your assistant pays for every tool result in its context window.
  • The first call of a session is slow. Expect 10 to 20 seconds while the mcp-remote bridge cold-starts. Everything after that is fast.
  • Use the right tool for the job. catalog_search and security_search for exact identifiers; ask_mdo_surge for explanations, examples, and formulas. Look identifiers up separately from code examples rather than in one combined question.
  • Your PAT will expire. When it does, generate a new one and replace the old value in your config file.

Back to Top

Troubleshooting

SymptomWhat to check
Both servers fail to startnode --version must report v18 or newer, and npx --version must run without error. Confirm the Snowflake account URL is reachable from your network.
One server connects, the other returns 404The app names are swapped. MDO_CATALOG_MCP_SERVER must sit under your MDO SDK app; MDO_SURGE_MCP_SERVER must sit under your Surge app.
Unauthorized or ForbiddenThe PAT has expired, or your user is not covered by the required authentication and network policies. Regenerate the token first, then ask your admin to verify the policies.
An OAuth dialog appearsThe client is configured with an HTTP URL instead of the mcp-remote stdio bridge. Switch to the command / args form.
The assistant ignores the toolsConfirm the config file is in the directory the client actually reads, that the filename is exact (including any leading dot), and restart the client. For Copilot, confirm you are in Agent mode.
catalog_search returns nothingThe Cortex Search service may still be indexing — large catalogs take 7 to 10 minutes after the admin setup runs. Ask your admin to confirm the services finished building.
import mdosnow failsThe wheel was installed into a different virtual environment than the one in use. Run python -c "import mdosnow; print(mdosnow.__file__)" and confirm the path.

For anything not covered here, contact MDO support at support@mydataoutlet.com.

Back to Top