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:
- Generate a Programmatic Access Token (PAT) in Snowsight.
- Point the client at one or two Snowflake MCP server URLs, bridged
through
mcp-remoteover stdio. - 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.
Prerequisites
From your Snowflake administrator, collect four things:
| Item | Example |
|---|---|
| Snowflake account identifier | myorg-myaccount |
| MDO SDK app name | MDOSDK |
| MDO Surge app name | SURGE or MDO_SURGE |
Latest mdosnow wheel | mdosnow-<version>-py3-none-any.whl |
On your own machine:
- Node.js v18 or newer — required for the
npxMCP bridge. Verify withnode --version. - Python 3.11 (3.9–3.13 supported) with a virtual environment where
mdosnowis 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.
Step 1: Generate a Snowflake PAT
The MCP servers authenticate with a Programmatic Access Token tied to your Snowflake user.
- In Snowsight, click your user icon (bottom-left) → Profile.
- Open the Authentication tab.
- Under Programmatic access tokens, click Generate token.
- Name it something descriptive, such as
claude-code-mcp. - Set an expiration that matches your organization’s policy — 90 days is common.
- 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.
Step 2: Know the Two URLs
There are two MCP servers, and they live in different Snowflake apps:
| Server name | Tools | URL path |
|---|---|---|
mdo-catalog | catalog_search, security_search | .../databases/<MDO-SDK-app>/schemas/APP_AI_API/mcp-servers/MDO_CATALOG_MCP_SERVER |
mdo-surge | ask_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.
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.
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.
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.
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
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.
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-remotebridge cold-starts. Everything after that is fast. - Use the right tool for the job.
catalog_searchandsecurity_searchfor exact identifiers;ask_mdo_surgefor 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.
Troubleshooting
| Symptom | What to check |
|---|---|
| Both servers fail to start | node --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 404 | The 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 Forbidden | The 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 appears | The client is configured with an HTTP URL instead of the mcp-remote stdio bridge. Switch to the command / args form. |
| The assistant ignores the tools | Confirm 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 nothing | The 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 fails | The 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.