Custom MCP servers

Custom MCP servers let Monte Carlo agents use tools from your other systems. You connect a remote Model Context Protocol (MCP) server, such as one for your ticketing system, wiki, or orchestration tool. The agents can then call its tools to bring in context that Monte Carlo does not collect on its own.

For example, with a Jira MCP server connected, the Operations Agent can look up the ticket linked to a pipeline change. The Troubleshooting Agent can check an incident tracker or a deployment log while it investigates an alert.

Which agents use custom MCP servers

Other agents do not use custom MCP servers.

Each tool call an agent makes is recorded in the account audit log. The entry shows the agent, the user it acted for, the server, the tool and whether the call succeeded. Tool arguments and results are not recorded.

Agents only call tools that your MCP server marks as read-only, with the MCP readOnlyHint annotation set to true. Tools without that annotation are not offered to the agent. Make sure your server annotates the tools you want the agents to use.

The AWS MCP Server is the exception. Your collection agent calls it from inside your AWS account, and its script tool can change resources as well as read them. The IAM role you give it is what limits the agents.

Requirements

• The server must use HTTPS and be reachable from the internet. Monte Carlo calls it from Monte Carlo's cloud.
• The server URL must not resolve to a private or reserved IP address.
• Servers that only support the older HTTP with SSE transport work with the agents, but the connection test that runs when you add or save the server may report an error for them.

Add an MCP server

You need the settings/mcp-servers/edit permission. By default, only Account Owners have it. See MCP Servers permissions.

1. Go to Settings > MCP servers, under Agentic operations.
2. Click Add. If you have no MCP servers yet, click Add MCP server, or click one of the suggested servers to start with its details filled in.
3. Under Server, choose one of your integrations or a recommended server to fill in the details, or choose Custom to enter them yourself.
4. Check the Name, such as "Jira MCP", and add an optional Description. The agent sees the name, so pick one that describes the system.
5. Enter the MCP server URL, if it isn't filled in.
6. Choose how Monte Carlo authenticates:
   • For GitHub, Linear, dbt Cloud, and Databricks servers, Monte Carlo offers your existing integration's credentials and selects them by default. See Reuse a Monte Carlo integration.
   • Otherwise, choose an Authentication method. Monte Carlo checks the URL and pre-fills OAuth settings when the server advertises them. See Authentication methods.
7. Click Add. Monte Carlo saves the server and tests the connection. If the test fails, the server is still saved, and the page stays open with the error so you can fix the settings and click Save.

To check the settings before you add the server, click Test connection. It isn't available when you use an integration's credentials.

If you use OAuth with your own client ID, Monte Carlo then shows a Redirect URI. Add it as a callback URL in your OAuth app before users connect.

To test a saved server again, click Test connection on its row. To change or remove a server, use Edit or Delete in the row's menu. Saving an edit tests the connection again. Saved secrets are never shown again. If you change the server URL, you must enter the secrets again, and every user must connect again.

Authentication methods

None

Monte Carlo sends requests without credentials.

Reuse a Monte Carlo integration

If you already connected GitHub, Linear, dbt Cloud, or Databricks to Monte Carlo, you can use that integration's credentials for its MCP server. You don't need to create keys or an OAuth app, and automated agent runs can use the server.

After you enter a supported URL, Monte Carlo shows the integration under Credentials and selects it by default, for example Use the Monte Carlo GitHub integration. To use another method, choose Set up authentication manually.

You need the settings/integrations/edit permission as well as settings/mcp-servers/edit. By default, only Account Owners have both.

Integrations whose credentials are stored in your own secret manager can't be reused.

For Linear, dbt Cloud, and Databricks, Monte Carlo copies the credentials when you add the server. If you later rotate the integration's credentials, edit the MCP server and enter the new ones. For GitHub, the server follows the GitHub App installation, so changing which repositories the app can access changes what the agents can read.

API key

Enter the API key and a Header name. With the default Authorization header, Monte Carlo sends Bearer <key>. With any other header name, Monte Carlo sends the key as it is.

Click Add header to send more headers, for example when a server needs both an API key and an application key.

User identity header

With None or API key authentication, every user shares the same credentials. To tell your server which Monte Carlo user is calling, set a User identity header, for example X-User-Email. Then pick the Identity field to send:

• Email address: the user's Monte Carlo email.
• User ID (Monte Carlo): the user's Monte Carlo user ID.

With Email address, Monte Carlo does not send the header for runs that Monte Carlo starts automatically. Those runs use a service user that has no real email.

OAuth 2.0 with client credentials

Monte Carlo gets a token from your authorization server with a client ID and secret, and uses it for every user. Enter:

• Client ID and Client secret
• Token endpoint
• Scopes, if your server needs them
• Token endpoint authentication: Basic (Authorization header) or Post (request body)
• Resource (RFC 8707) and Audience, if your authorization server needs them

OAuth 2.0 with authorization code (PKCE)

This method follows the MCP authorization specification, based on OAuth 2.1. Each user signs in to the other system with their own account. The agent then acts with that user's access.

Monte Carlo discovers the authorization server from the MCP server URL, using OAuth Protected Resource Metadata (RFC 9728) and Authorization Server Metadata (RFC 8414).

• If the authorization server supports dynamic client registration, turn on Dynamic client registration (DCR). Monte Carlo registers its own client. You do not need a client ID.
• If it does not, create an OAuth app in the other system and enter its Client ID and Client secret. Then add the Redirect URI that Monte Carlo shows to your OAuth app.

Users must connect their own account before the agents can use the server for them. See Connect your account.

Agent runs that Monte Carlo starts automatically cannot use this method, because no user is there to sign in. For example, a Troubleshooting Agent investigation started by the Triage Agent skips these servers. IIf automated runs need the server, reuse a Monte Carlo integration, or use API key or client credentials authentication, or your own GitHub App for GitHub. See How the Troubleshooting Agent uses credentials.

Your own GitHub App

This method is only available for GitHub's MCP server, https://api.githubcopilot.com/mcp/. Enter:

• App ID
• Private key: the .pem file GitHub generates for the app
• Installation ID

For each agent run, Monte Carlo creates a short-lived installation token. The token only has read access, even if the app has write permissions. Monte Carlo stores the private key in its vault and never shows it again. If you change the App ID or installation ID, you must enter the private key again.

See GitHub with your own GitHub App.

Examples

These examples use public MCP servers from other vendors. Check the vendor's docs for the current URL and options. If your account has the matching Monte Carlo integration, Monte Carlo selects its credentials by default. To follow these steps instead, choose Set up authentication manually first.

Datadog with API keys

The Datadog MCP Server accepts an API key and an application key in two headers.

1. In Datadog, create a service account with only the permissions the agents need. Create an API key and an application key for it.
2. In Monte Carlo, add a server with:
   • Name: Datadog
   • MCP server URL: https://mcp.datadoghq.com/v1/mcp. Use the endpoint for your Datadog site, for example https://mcp.datadoghq.eu/v1/mcp.
   • Authentication: API key
   • Header name: DD_API_KEY, with your API key as the API key
3. Click Add header. Enter DD_APPLICATION_KEY as the name and your application key as the value.
4. Click Test connection, then Add.

Every user's agent uses the service account's access.

Notion or Linear with OAuth 2.1

Notion and Linear host MCP servers that support OAuth 2.1 with dynamic client registration. You do not need to create an OAuth app.

1. In Monte Carlo, add a server with:
   • Name: Notion or Linear
   • MCP server URL: https://mcp.notion.com/mcp or https://mcp.linear.app/mcp
2. Monte Carlo detects the OAuth settings. Check that Authentication is OAuth 2.0, Grant type is Authorization code (PKCE), and Dynamic client registration (DCR) is on.
3. Click Add.
4. Each user connects their own Notion or Linear account. See Connect your account.

The agents then see only the pages or issues each user can see.

GitHub with your own OAuth app

The GitHub MCP Server supports OAuth with PKCE, but not dynamic client registration. You create an OAuth app in GitHub and give Monte Carlo its client ID and secret.

1. In GitHub, go to Settings > Developer settings > OAuth Apps and click New OAuth App. For an organization-owned app, use the organization's settings.
2. Enter an Application name and a Homepage URL. GitHub requires an Authorization callback URL to create the app. Enter your Monte Carlo URL for now, and replace it in step 7.
3. Click Register application. Copy the Client ID, then click Generate a new client secret and copy the secret.
4. In Monte Carlo, add a server with:
   • Name: GitHub
   • MCP server URL: https://api.githubcopilot.com/mcp/
5. Monte Carlo detects the OAuth settings. Check that Authentication is OAuth 2.0 and Grant type is Authorization code (PKCE). Leave Dynamic client registration (DCR) off, and enter the Client ID and Client secret.
   Monte Carlo fills in Scopes with every scope GitHub offers. Remove the ones you don't want users to grant, such as write:packages or gist.
6. Click Add. Monte Carlo shows a Redirect URI. Copy it.
7. In your GitHub OAuth app, set the Authorization callback URL to the redirect URI, and click Update application.
8. Each user connects their own GitHub account. See Connect your account.

You can find the redirect URI later on the server's Edit page. If your organization restricts OAuth app access, an organization owner must approve the app before users can see its repositories.

GitHub with your own GitHub App

A GitHub App gives every user's agent the same read-only access to the repositories you choose. Users don't need to connect their own GitHub account, so automated agent runs can use it too.

1. In GitHub, go to your organization's Settings > Developer settings > GitHub Apps and click New GitHub App.
2. Enter a GitHub App name and a Homepage URL. Under Webhook, clear Active.
3. Under Repository permissions, give read-only access to what the agents need, for example:
   • Contents: Read-only
   • Metadata: Read-only
   • Pull requests: Read-only
   • Issues: Read-only
4. Under Where can this GitHub App be installed?, choose Only on this account, then click Create GitHub App.
5. On the app's page, copy the App ID. Under Private keys, click Generate a private key. GitHub downloads a .pem file.
6. Click Install App, install it on your organization, and choose the repositories the agents may read.
7. After the install, GitHub opens the installation's settings page. Copy the number at the end of its URL, https://github.com/organizations/<org>/settings/installations/<installation ID>. That is the Installation ID.
8. In Monte Carlo, add a server with:
   • Name: GitHub
   • MCP server URL: https://api.githubcopilot.com/mcp/
   • Authentication: Use your own GitHub App
   • App ID, Private key (paste the contents of the .pem file) and Installation ID
9. Click Test connection, then Add.

To give the agents access to more repositories later, change the app's installation in GitHub. You don't need to change the server in Monte Carlo.

Connect your account

When a server uses the authorization code (PKCE) method, each user connects once:

1. Open a chat with the Operations Agent.
2. Click the MCP servers button in the message box. A badge shows how many servers need you to connect.
3. Click Connect next to the server.
4. Sign in to the other system in the new tab and approve access.
5. Go back to Monte Carlo. The server moves to Active.

Until you connect, the agents skip that server in your conversations and investigations.

If your browser blocks pop-ups, allow them for Monte Carlo and try again.

Revoke a connection

Admins with the settings/mcp-servers/edit permission can see and revoke connections. Go to Settings > MCP servers, and choose Connected users on the server's row. After you revoke a connection, that user must connect again before the agents can use the server for them.

Revoking in Monte Carlo deletes the stored tokens. It does not revoke the grant in the other system. To revoke it there, use that system's own settings.

How the Troubleshooting Agent uses credentials

The Troubleshooting Agent uses the credentials of the user who runs the investigation:

• Servers with None, API key, or client credentials authentication work for any investigation.
• Servers with authorization code (PKCE) authentication work only when the user who started the investigation has connected their account.

Investigations that start from the Monte Carlo UI or the Slack Troubleshoot alert button run as the user who clicked. Investigations that Monte Carlo starts automatically, such as from the Triage Agent, run as a Monte Carlo service user. They can only use servers with None, API key, or client credentials authentication.

Limits

• Monte Carlo waits up to 10 seconds for each server to list its tools. A server that does not answer in time is skipped for that run.
• In the Troubleshooting Agent, each tool call times out after 20 seconds, except calls to the AWS MCP Server, which can take longer. Tool results are cut to 6,000 characters.
• Agents decline requests from your server to ask the user for input during a tool call.

Troubleshooting

If the agent does not use a tool you expect, check that your server marks the tool as read-only with readOnlyHint: true.

Security & data privacy

For how Monte Carlo stores credentials and handles tool results, see Custom MCP Servers Technical Overview.

FAQ

What can the agents do with my MCP server?

The agents only call tools that your server marks as read-only. They cannot call tools that create, change, or delete data.

The AWS MCP Server is the exception: the IAM role you create sets what the agents can do in your AWS account.

Does the agent send my credentials to the LLM?

No. Credentials are sent only to your MCP server, in request headers. The LLM sees tool names, descriptions, and results.

Can users see each other's data through a shared server?

With None, API key, or client credentials, every user's agent acts with the same identity. Any user can get the same results. Use the authorization code (PKCE) method if each user should only see their own data.