> For the complete documentation index, see [llms.txt](https://docs.telm.ai/telmai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telm.ai/telmai/integrations/telmai-mcp-server.md).

# Telmai MCP Server

## Overview

Telmai's Model Context Protocol (MCP) server connects AI assistants such as Claude and Microsoft 365 Copilot to Telmai, so you can work with your data quality platform in plain language. The assistant gets Telmai's tools for monitoring, alerting and data quality management, and every call runs with your own Telmai permissions.

### What is MCP?

The Model Context Protocol (MCP) is a standard that lets AI applications connect securely to external services and data sources. Telmai's MCP server exposes the platform's capabilities as tools that a compatible AI assistant calls when your question needs them.

## Connect a client

| Client                       | How it signs in                                                                          | Setup                                                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Claude Desktop and Claude.ai | OAuth, from Claude's connector settings                                                  | [Claude](https://docs.telm.ai/telmai/integrations/telmai-mcp-server/mcp-claude.md)                           |
| Microsoft 365 Copilot        | OAuth, through an agent package your Microsoft 365 admin deploys. The agent is read-only | [Microsoft 365 Copilot](https://docs.telm.ai/telmai/integrations/telmai-mcp-server/mcp-microsoft-copilot.md) |
| VS Code Cline                | A bearer token you generate and refresh                                                  | [VS Code Cline](https://docs.telm.ai/telmai/integrations/telmai-mcp-server/mcp-vscode-cline.md)              |

Other clients that support remote MCP servers with OAuth connect the same way as Claude.

Once you're connected, see [Sample Prompts](https://docs.telm.ai/telmai/integrations/telmai-mcp-server/mcp-sample-prompts.md) for prompts to try.

## Before you begin

* Valid sign-in credentials for your tenant's identity provider: your organization's SSO provider or Telmai-managed Okta, depending on how your tenant is configured
* The MCP server URL for your environment: see [Server URL](#server-url)
* For Claude and VS Code Cline, the OAuth client ID for your environment

{% hint style="warning" %}
**Important**

1. You must be assigned to the associated application in your identity provider to complete OAuth sign-in.
2. Get the MCP server URL and client ID from your Telmai deployment owner.
3. A client secret is needed only for clients that use bearer token authentication, such as VS Code Cline.
   {% endhint %}

## Server URL

Clients connect to one of two MCP URLs:

| Connection  | MCP URL                                  | Serves                                     |
| ----------- | ---------------------------------------- | ------------------------------------------ |
| Per tenant  | `https://<mcp-endpoint>/<tenant-id>/mcp` | One Telmai tenant                          |
| All tenants | `https://<mcp-endpoint>/all/mcp`         | Every tenant you hold, from one connection |

* `<mcp-endpoint>` is your Telmai MCP endpoint: `mcp.env1.telm.ai` on SaaS, for example `https://mcp.env1.telm.ai/<tenant-id>/mcp`.
* `<tenant-id>` is your tenant ID, which you can read from your Telmai URL.

{% hint style="info" %}
VPC and Hybrid deployments have their own MCP endpoint. Ask your Telmai deployment owner for the one that applies to your environment.
{% endhint %}

### Signing in on the all-tenants URL

On the all-tenants URL, you sign in through Telmai's own sign-in page instead of going straight to your identity provider:

1. Enter your work email. This step is skipped when you're already signed in to Telmai in that browser.
2. Telmai sends you to your company's SSO or to the Okta password page.
3. When you hold several tenants, the assistant lists them and asks which one to use, once per conversation.

An SSO sign-in covers the tenants behind that one identity provider. If you also hold tenants behind another identity provider, connect again to reach them.

***

## Available Tools

Once connected, your AI assistant has access to these Telmai capabilities:

* Asset Management
* Connection Management
* Monitors Management
* Incidents & Alerts
* Data Quality Metrics
* Integration & Workflow
* Project & User Management

***

## Security Considerations

### OAuth Authentication (Recommended)

* Uses the industry-standard OAuth 2.0 protocol
* Tokens are managed by your AI client: Claude, or Microsoft's token store for Copilot
* Tokens refresh automatically
* Access can be revoked immediately from your identity provider's admin console
* Access events leave an audit trail

### Bearer Token Authentication

* Tokens expire after a set period (typically one hour)
* Treat tokens as passwords: never commit them to version control
* Regenerate tokens regularly
* Revoke compromised tokens immediately through your identity provider

### Best Practices

1. **Never share your client secret or bearer tokens.**
2. **Use separate OAuth applications** for production and development environments.
3. **Regularly audit** connected applications in your identity provider's dashboard.
4. **Revoke access** for applications you no longer use.

***

## Troubleshooting

Each client page has its own troubleshooting section: [Claude](https://docs.telm.ai/telmai/integrations/telmai-mcp-server/mcp-claude.md#troubleshooting), [Microsoft 365 Copilot](https://docs.telm.ai/telmai/integrations/telmai-mcp-server/mcp-microsoft-copilot.md#troubleshooting) and [VS Code Cline](https://docs.telm.ai/telmai/integrations/telmai-mcp-server/mcp-vscode-cline.md#troubleshooting). These problems apply to every client:

| Problem                                                   | Solution                                                                                                    |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| "User not authorized" or `access_denied` after signing in | Ask your identity provider admin to assign your user to the Telmai application                              |
| Telmai's tools don't appear                               | Check that the client shows the connection as connected, then start a new conversation to refresh the tools |
| Tools return "not found" errors                           | Check the MCP server URL and, for a per-tenant URL, the tenant ID. See [Server URL](#server-url)            |
