Connect agents to the Rel app MCP server
Connect AI agents, such as Claude Code and Codex, to your Rel app instance so they can answer questions with the models deployed to it. The Rel app includes a Model Context Protocol (MCP) server, which lets agents call its tools. An administrator turns on MCP once for the instance, and then each person connects their own agent.
- Prerequisites
- A Rel app instance connected to Snowflake in Snowflake deployed mode. See Set up the Rel app.
- At least one model the Rel app lists. See Deploy a model.
- For administrators: the
ACCOUNTADMINrole, or a role with theCREATE ROLE,CREATE INTEGRATION, andMANAGE GRANTSprivileges, plus a warehouse you can use. You also need a Rel app administrator account. - For users: Claude Code, Codex, or Snowflake CoWork, and a Snowflake user that has been granted the MCP sign-in role.
How MCP access works
Section titled “How MCP access works”Before you turn on MCP, decide who can connect and what data they can reach:
- Who can connect: people who sign in to Snowflake and choose the sign-in role, a Snowflake role you create for this purpose. The sign-in role controls access to the MCP server and doesn’t need any privileges of its own.
- What they can query: every MCP request runs as the Snowflake user and role configured in the Rel app, not as the person who signed in.
- What each question does: the Rel app answers with its configured language model and runs queries on its warehouse. See Reference: Rel app MCP tools for what each tool returns and changes.
Grant REL_APP_ROLE access only to the data you want agents to reach, and grant the sign-in role only to the people who should connect.
Set up MCP
Section titled “Set up MCP”A Snowflake administrator and a Rel app administrator do this once for each Rel app instance. If MCP is already on, skip to Connect an agent.
Check network access for PrivateLink instances
Section titled “Check network access for PrivateLink instances”Create the sign-in role and OAuth integration
Section titled “Create the sign-in role and OAuth integration”A Snowflake administrator creates a Snowflake OAuth integration for your Rel app instance. Agents use it to sign people in with their Snowflake accounts.
Run the following statements in a Snowsight SQL worksheet:
-
(Optional) Create the sign-in role and grant it to users
Create a role for MCP sign-in and grant it to each Snowflake user who should connect:
USE ROLE ACCOUNTADMIN;CREATE ROLE IF NOT EXISTS <mcp-signin-role>;GRANT ROLE <mcp-signin-role> TO USER <user_name>;Repeat the
GRANTstatement for each user. Replace<mcp-signin-role>with any role name, such asREL_APP_MCP_ROLE. You can’t useACCOUNTADMINorSECURITYADMINas the sign-in role, because Snowflake blocks them for OAuth by default. -
Create the OAuth integration
Create the integration, replacing
<rel-app-host>with the hostname from your Rel app URL, withouthttps://, and<mcp-signin-role>with your sign-in role:CREATE SECURITY INTEGRATION IF NOT EXISTS REL_APP_MCP_OAUTHTYPE = OAUTHOAUTH_CLIENT = CUSTOMOAUTH_CLIENT_TYPE = 'PUBLIC'OAUTH_REDIRECT_URI = 'https://<rel-app-host>/mcp/oauth/snowflake-callback'OAUTH_ENFORCE_PKCE = TRUEOAUTH_ISSUE_REFRESH_TOKENS = TRUEOAUTH_REFRESH_TOKEN_VALIDITY = 7776000ALLOWED_ROLES_LIST = ('<mcp-signin-role>')OAUTH_ENABLE_ROLE_SELECTION = TRUEENABLED = TRUECOMMENT = 'Rel App MCP OAuth client (PUBLIC, PKCE-enforced)';The integration is a public OAuth client, so it has no client secret.
OAUTH_REFRESH_TOKEN_VALIDITYkeeps people signed in for up to 90 days, after which they sign in again.If another Rel app instance already uses this Snowflake account, give each instance’s integration a different name.
-
Copy the client ID
Select a running warehouse in the worksheet, then read the integration’s client ID:
SELECTPARSE_JSON(SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('REL_APP_MCP_OAUTH')):OAUTH_CLIENT_ID::STRING AS CLIENT_ID;Output CLIENT_ID<a long alphanumeric string>The result has one row with the client ID. Give it to your Rel app administrator for the next section. The client ID identifies the integration and isn’t a secret.
If the query fails because no warehouse is in use, select a warehouse in the worksheet and run it again.
Turn on MCP in the Rel app
Section titled “Turn on MCP in the Rel app”A Rel app administrator turns on the MCP server and connects it to the OAuth integration. In the Rel app, do the following:
-
Open Settings.
-
In the MCP section, select Enable MCP.
-
In Client ID, paste the client ID from the previous section.
-
Choose Save settings.
The change applies right away, without restarting the Rel app, and agents can connect after you save.
If saving fails with either of the following errors, your instance isn’t ready for MCP yet. Contact your RelationalAI account team.
MCP authentication must be configured by an operator before it can be enabled.OAuth cannot be configured until APPLICATION__MCP_OAUTH_DEPLOYMENT_SIGNING_KEY is set as a stable deployment secret.
Share the MCP server URL with your users, and tell them which sign-in role to choose.
The URL is https://<rel-app-host>/mcp/, where <rel-app-host> is the hostname from your Rel app URL.
For PrivateLink instances, use the private hostname.
Connect an agent
Section titled “Connect an agent”Each person who connects needs the Rel app MCP server URL, https://<rel-app-host>/mcp/, and the sign-in role.
Select your agent:
-
Add the Rel app MCP server
In a terminal, run:
Terminal window claude mcp add --transport http rel-app https://<rel-app-host>/mcp/The server is available in the current project by default. Add
--scope userto make it available in every project. -
Start sign-in
In Claude Code, run
/mcp, selectrel-app, and follow the prompt to authenticate. You can also runclaude mcp login rel-appfrom a terminal. -
Sign in to Snowflake
Your browser opens the sign-in flow:
- If the Rel app shows an Application Access Request page, choose Allow Access.
- Sign in with your Snowflake user.
- On Snowflake’s consent screen, choose the sign-in role and allow access.
If the consent screen has no role to choose, the sign-in role hasn’t been granted to your user. Ask your Snowflake administrator to grant it, then sign in again.
To sign in again or sign out, run /mcp, select rel-app, and choose Re-authenticate or Clear authentication.
To remove the server, run claude mcp remove rel-app.
The Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share MCP settings in ~/.codex/config.toml, so you only need to add the server once.
-
Add the Rel app MCP server
In a terminal, run:
Terminal window codex mcp add rel-app --url https://<rel-app-host>/mcp/In the ChatGPT desktop app, you can instead open Settings, select MCP servers, select Add server, choose Streamable HTTP, enter the URL, save, and then select Restart.
-
Start sign-in
In a terminal, run:
Terminal window codex mcp login rel-appIn the ChatGPT desktop app, select Authenticate next to the server in Settings > MCP servers.
-
Sign in to Snowflake
Your browser opens the sign-in flow:
- If the Rel app shows an Application Access Request page, choose Allow Access.
- Sign in with your Snowflake user.
- On Snowflake’s consent screen, choose the sign-in role and allow access.
If the consent screen has no role to choose, the sign-in role hasn’t been granted to your user. Ask your Snowflake administrator to grant it, then sign in again.
To sign in again, run codex mcp login rel-app.
To sign out, run codex mcp logout rel-app.
To remove the server, run codex mcp remove rel-app.
Snowflake CoWork and Cortex Agents connect to the Rel app through a Snowflake MCP connector. They run in Snowflake, so they can’t reach a Rel app instance that’s available only through PrivateLink.
-
Add the Rel app to an agent
A Snowflake administrator creates the connector by following Snowflake’s MCP Connectors guide with these values:
- An API integration with
API_PROVIDER = external_mcp,https://<rel-app-host>/mcp/inAPI_ALLOWED_PREFIXES, and user authentication of typeOAUTH_DYNAMIC_CLIENTwithOAUTH_RESOURCE_URLset to the MCP server URL. - An external MCP server object, created with
CREATE EXTERNAL MCP SERVER, that uses the MCP server URL and the API integration. USAGEon the API integration and the external MCP server object for the roles that use the agent.- The MCP server added to a Cortex agent with
ALTER AGENT ... ADD MCP_SERVER.
To create an agent first, see Create a Snowflake agent with semantic views.
- An API integration with
-
Connect in CoWork
Each user opens the agent in Snowflake CoWork, opens the sources panel, selects Connectors, and selects Connect next to the Rel app connector.
-
Sign in to Snowflake
Complete the sign-in flow:
- If the Rel app shows an Application Access Request page, choose Allow Access.
- Sign in with your Snowflake user.
- On Snowflake’s consent screen, choose the sign-in role and allow access.
If the consent screen has no role to choose, the sign-in role hasn’t been granted to your user. Ask your Snowflake administrator to grant it, then connect again.
Other agents aren’t tested with the Rel app MCP server. Sign-in fails if an agent uses a sign-in redirect address that the Rel app doesn’t allow. See Troubleshoot MCP connections.
To try another agent, add a remote MCP server with the URL https://<rel-app-host>/mcp/.
If the agent asks for a transport type, choose HTTP, which some agents call streamable HTTP.
Leave any OAuth client ID and client secret fields empty, because the agent registers with the server automatically.
Then sign in to Snowflake and choose the sign-in role.
After you sign in, the agent lists the Rel app tools: ask_model, list_models, whoami, and ping.
Check the connection
Section titled “Check the connection”Ask your agent to list the Rel app models it can query:
List the Rel app models I can query.The agent calls list_models and returns each model’s ID, name, and description.
This confirms that sign-in works and that the Rel app can read its models.
It doesn’t confirm that REL_APP_ROLE can read every table a model uses.
To check that, ask a question about one of the models.
To see which Snowflake identity answers requests, ask your agent to call whoami.
It returns the Rel app’s Snowflake user and role.
If the list is empty, ask your Rel app administrator to check that the Rel app uses Snowflake deployed mode with the correct persistence database, and that someone has deployed a model to that database. Models in branch schemas aren’t listed.
Ask questions
Section titled “Ask questions”Name the model you want to use, and ask in plain language. For example:
Using the Rel app model <model-id>, which suppliers have the most delayed shipments?What concepts and relationships does the Rel app model <model-id> define?Using the Rel app model <model-id>, list every overdue order. Return up to 500 rows.Replace <model-id> with an ID from list_models.
Answers include result tables and the SQL that produced them.
Result tables return up to 100 rows unless you ask for more, up to 1,000.
Change or turn off MCP
Section titled “Change or turn off MCP”Use these steps to change who can connect or to stop all MCP access:
- Turn off MCP: clear Enable MCP in the Rel app’s Settings and choose Save settings.
Agents then get
MCP is disabled.until you turn it back on. - Stop a person from signing in: revoke the sign-in role from their Snowflake user.
- Change the sign-in role or Rel app URL: drop the integration and create it again with the new values.
To drop the integration, run:
DROP SECURITY INTEGRATION IF EXISTS REL_APP_MCP_OAUTH;Creating the integration again issues a new client ID. A Rel app administrator must paste the new ID into Client ID in the MCP section of Settings, and then everyone signs in again. Until then, no one can sign in to the MCP server.
Troubleshoot MCP connections
Section titled “Troubleshoot MCP connections”What if sign-in fails with a redirect URI error?
If your agent shows Redirect URI '<uri>' does not match allowed patterns. or invalid_redirect_uri, the agent uses a sign-in redirect address that the Rel app doesn’t allow.
Connect with Claude Code, Codex, or Snowflake CoWork instead by following Connect an agent.
To use a different agent, contact your RelationalAI account team.
What if sign-in fails because my agent isn’t registered?
If your agent shows Client Not Registered, the server no longer recognizes your agent’s registration.
This can happen after RelationalAI changes the server’s signing key.
Remove the Rel app MCP server from your agent, then add it again and sign in by following Connect an agent.
If the error continues, contact your RelationalAI account team.
What if my agent says MCP is disabled?
If your agent shows MCP is disabled., MCP is turned off for the Rel app instance.
Ask your Rel app administrator to select Enable MCP in Settings and save.
Then check the connection again.
What if my agent says the Rel app needs a Snowflake connection?
If your agent shows Configure Snowflake in the runtime settings to enable /mcp., MCP is turned on, but the Rel app can’t connect to Snowflake.
Ask your Rel app administrator to check the Snowflake section in Settings.
See Connect the Rel app to Snowflake.
Then check the connection again.
What if my questions fail because no agent is configured?
If your agent shows Agent capability is unavailable. Configure an agent in Runtime Settings., the Rel app has no language model configured to answer questions.
Ask your Rel app administrator to configure the LLM section in Settings.
Then ask your question again.
What if my agent can’t find a model?
If your agent shows Model not found: <id>, the model ID doesn’t match a model the Rel app lists.
Ask your agent to call list_models, then ask your question again with an ID from the result.
If the model you want isn’t listed, see Check the connection.
Reference: Rel app MCP tools
Section titled “Reference: Rel app MCP tools”The Rel app MCP server provides these tools:
| Tool | Inputs | Returns |
|---|---|---|
ask_model | question, model_id, and optional row_limit from 1 to 1000, which defaults to 100 | An answer grounded in the model, with a summary, result tables and the SQL that produced them, and any caveats. Unless RelationalAI has made the instance read-only, a request can also create or edit model content. The Rel app saves the question and its steps to the model’s history. |
list_models | None | The ID, name, and description of each model the Rel app lists. |
whoami | None | The Snowflake user and role that answer MCP requests. |
ping | None | modeler-mcp-ok, which confirms the server is reachable. |