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.

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.

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.
• The server should support the Streamable HTTP transport. Servers that only support the older HTTP with SSE transport work with the agents, but Test connection 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 MCP server.
3. Enter a Name, such as "Jira MCP", and an optional Description. The agent sees the name, so pick one that describes the system.
4. Enter the MCP server URL.
5. Choose an Authentication method. Monte Carlo checks the URL and pre-fills OAuth settings when the server advertises them. See Authentication methods.
6. Click Test connection to check the settings.
7. Click Add.

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 change or remove a server, use Edit or Delete on its row. 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.

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. If automated runs need the server, use API key or client credentials authentication. See How the Troubleshooting Agent uses credentials.

Examples

These examples use public MCP servers from other vendors. Check the vendor's docs for the current URL and options.

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 in the server's Edit drawer. If your organization restricts OAuth app access, an organization owner must approve the app before users can see its repositories.

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. 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.

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.