> For the complete documentation index, see [llms.txt](https://docs.teleskope.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.teleskope.ai/the-platform/mcp.md). # MCP {% hint style="info" %} MCP access may not be enabled for your organization yet. Contact your Technical Account Manager to enable. {% endhint %} ## What is Teleskope MCP? Teleskope MCP lets you use Teleskope from your own AI client, such as Claude Code, instead of logging into the Teleskope UI. Your AI client connects to Teleskope through the Model Context Protocol (MCP), an open standard for connecting AI tools to data sources. You ask questions in plain language, and your client calls Teleskope tools to answer them. Every request runs as you, with your existing Teleskope role and connector access. MCP doesn't add any privileges. *** ## What Would You Use It For? * **Query findings without opening the UI.** Ask which resources contain a data element, or which findings are open for a connector. * **Slice and dice in plain language.** Get exact counts and groupings, such as findings by connector, category, or severity. * **Triage findings.** Run a triage scenario that groups findings by risk, with counts and a recommended action for each group. * **Generate reports.** Create a report from your AI client. It appears in Teleskope like any report built in the UI. * **Turn results into deliverables.** Ask your AI client to turn a report or triage result into a slide deck, an AI governance plan, or a briefing for HR. Your client writes the document from the data Teleskope returns. * **Work with policies.** List and inspect policies, draft and save new ones, and disable one if you have Policy Maker Create & Edit access. New policies are always saved disabled, and enabling a policy stays in Teleskope. * **Get oriented.** Built-in how-to tools explain what you can do and where the limits are, so new team members can ask the AI instead of a colleague. For the complete list of tools, see the [MCP Tools Reference](/the-platform/mcp/tools-reference.md). *** ## Before You Begin * MCP is enabled for your Teleskope deployment. It's off by default. Your Technical Account Manager can turn it on. * You have a Teleskope user account. MCP uses the same sign-in and the same roles as the Teleskope UI. * You have the MCP server URL for your deployment. Your Technical Account Manager will provide it. The URL ends in `/v1/mcp`. If MCP isn't enabled, the server's hostname won't resolve. * You use an AI client that supports remote MCP servers. See Other MCP clients below. * Your Teleskope role includes MCP access. By default the Admin and Teleskope Support roles have it. If you're unsure, ask your administrator. *** ## Connect Your AI Client ### Claude Code 1. Add the server, replacing the URL with the one for your deployment: ```bash claude mcp add --transport http teleskope ``` `http` here is the name of the MCP transport (Streamable HTTP), not the URL scheme. Your server URL starts with `https://`, so the connection is encrypted, and plain-HTTP requests are redirected to HTTPS. 2. Start Claude Code and run `/mcp`. 3. Select **teleskope** and choose to authenticate. Your browser opens to the Teleskope sign-in. 4. Sign in and review the consent screen, which shows which AI client is asking for access. Approve it. 5. Back in Claude Code, ask: "Who am I in Teleskope?" The `kosmo_whoami` tool returns the account and permissions the server sees for you. For more on adding and managing servers in Claude Code, see [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp). ### Other MCP clients A client can connect if it supports remote MCP servers over Streamable HTTP and OAuth 2.1 with PKCE, registers through dynamic client registration or a client ID metadata document, and finishes sign-in on a loopback address (such as `http://127.0.0.1`) or an app link (a custom URL scheme). Claude Code, Cursor, and Codex have been tested end to end. Teleskope also accepts the sign-in redirects used by VS Code, Windsurf, and Zed. Clients that finish sign-in on a web page can't connect today. That includes Claude on the web, custom connectors in Claude Desktop, and ChatGPT. Teleskope follows the MCP authorization specification and doesn't relax it for individual clients. *** ## Sign-In and Consent Teleskope MCP uses OAuth 2.1 with PKCE. The first time a client connects, you sign in to Teleskope and approve that client on a consent screen showing the `mcp` scope. Each client you approve is a separate grant. If you've already approved a client on the same machine, it may reconnect without showing the consent screen again. Access tokens last 5 minutes. Your client refreshes them automatically using a refresh token that's valid for 30 days. *** ## Coverage Tools return data for the connectors your account can access. Ask your AI client to list your enrolled connectors (`kosmo_list_connectors`) to see what's covered in your deployment. *** ## What MCP Can't Do * **Enable policies.** You can draft, save, list, view, and disable policies. Saved policies are always switched off, and enabling one is a step you take in Teleskope. * **Run remediation actions.** Triage recommends actions, but you can't run remediation through MCP. * **Delete things or manage users.** There are no tools for deleting reports or policies, or for user management. * **Per-tool scoping.** MCP has a single `mcp` scope. What you can do follows the roles already assigned to you in Teleskope. *** ## Data Handling Results from Teleskope tools are returned to your AI client and sent to your AI provider as part of the conversation. Your provider's data handling terms apply to that content. Use a client and plan that match your organization's data policies. What the tools return: * **Search results** include, for each resource: file name, sensitivity label, risk tier and score, whether it's shared externally, finding details, owner name or email, document type, up to 12 data element labels, and size. Search returns up to 200 rows plus the full match count. * **Aggregate results** are counts and sums per group. They contain no file-level rows. * **Triage group files** list each file's catalog record, including its name, location (path and parent folder), owner, sensitivity, and data elements, 200 rows per page. * **Report results** show up to 50 rows per block, with the total count and a `rows_truncated` flag. Tools don't return file contents. Row visibility follows your account's connector access. For self-hosted deployments, no MCP telemetry leaves your environment unless Datadog monitoring is turned on for your deployment. *** ## Usage Limits * Operations that use AI draw from a per-session budget of 100 units by default. Search and aggregate cost 1 unit, and triage and reports cost 10. Lookups, how-tos, and policy tools don't count. When the budget runs out, Teleskope returns a clear error. * Triage and reports run in the background and typically take one to three minutes. Your client starts them and then checks for the result. * Triage groups and policy drafts are kept for the session. They expire after one hour of inactivity or when the service restarts. * Requests to the MCP endpoint are limited to 20 per second per client IP address by default, with bursts up to 40. Sign-in endpoints have their own, lower limits. Defaults can be changed per deployment.