> ## Documentation Index > Fetch the complete documentation index at: https://docs.devtune.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Connect Claude, Cursor, and other MCP-compatible coding agents to DevTune AI search visibility data with the Streamable HTTP Model Context Protocol server. DevTune exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so that AI agents can query your AI search visibility data directly. This lets agents like Codex, Claude, Cursor, and other MCP-compatible tools access your metrics and data directly. ## Server URL The server uses **Streamable HTTP** transport at: ```text theme={null} https://devtune.ai/api/mcp ``` The MCP server supports two setup paths: * **OAuth** for interactive tools like Codex * **API key** for non-interactive agents, CI jobs, or clients without OAuth support ## Setup ### Codex Codex users can install the DevTune plugin from the DevTune plugin marketplace: ```bash theme={null} codex plugin marketplace add devtunehq/codex-plugins --ref main ``` After adding the marketplace: 1. Restart Codex 2. Open the plugin list 3. Install the DevTune plugin 4. Sign in when Codex opens the browser authorization flow 5. Select the DevTune project the plugin should access Once authorized, ask Codex to use DevTune for visibility summaries, citations, competitive positioning, actions, traffic, adoption metrics, or content gaps. ### Other OAuth MCP Clients Use this configuration when your MCP client supports OAuth: ```json theme={null} { "mcpServers": { "devtune": { "type": "streamable-http", "url": "https://devtune.ai/api/mcp" } } } ``` When your client prompts for authorization, sign in to DevTune, select a project, and approve access. ### API Key Use API keys for non-interactive agents, CI jobs, or clients without OAuth support. Pass your key in the `Authorization` header: ```text theme={null} Authorization: Bearer dtk_live_your_key_here ``` #### Claude Desktop Add to your Claude Desktop config file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json theme={null} { "mcpServers": { "devtune": { "type": "streamable-http", "url": "https://devtune.ai/api/mcp", "headers": { "Authorization": "Bearer dtk_live_YOUR_API_KEY_HERE" } } } } ``` #### Cursor Open **Settings > MCP Servers > Add Server**, or edit `.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "devtune": { "type": "streamable-http", "url": "https://devtune.ai/api/mcp", "headers": { "Authorization": "Bearer dtk_live_YOUR_API_KEY_HERE" } } } } ``` #### Claude Code ```bash theme={null} claude mcp add devtune \ --transport http \ https://devtune.ai/api/mcp \ --header "Authorization: Bearer dtk_live_YOUR_API_KEY_HERE" ``` ## REST vs MCP Use REST when you are building an app, job, warehouse sync, dashboard, or webhook consumer. Use MCP when an AI agent should inspect DevTune data and decide what to do next inside a workflow. ## Available Tools | Category | Tool | Access | Description | | --------------- | ---------------------------------- | ------ | ------------------------------------------------------------------------------------- | | Overview | `devtune_get_visibility_summary` | Read | Share of voice, presence rate, brand awareness, and citation counts | | Diagnostics | `devtune_get_competitive_position` | Read | Competitive positioning time series (daily/weekly/monthly) | | Diagnostics | `devtune_get_citation_analysis` | Read | Backward-compatible alias for top citation pages | | Diagnostics | `devtune_get_top_citation_pages` | Read | Cursor-paginated top citation pages with URL, domain, classification, and position | | Diagnostics | `devtune_get_top_citation_domains` | Read | Cursor-paginated top citation domains with counts, unique URLs, and class totals | | Diagnostics | `devtune_get_citation_stats` | Read | Aggregate citation stats for the selected 30- or 90-day window | | Recommendations | `devtune_get_actions` | Read | Current actions workspace, including active recommendations and adopted backlog items | | Execution | `devtune_get_action_brief` | Read | Stored brief status and execution-ready markdown for a specific action | | Execution | `devtune_generate_action_brief` | Write | Queue or reuse command-center brief generation for a specific action | | Diagnostics | `devtune_get_traffic_summary` | Read | LLM bot and referral traffic analytics | | Diagnostics | `devtune_get_adoption_metrics` | Read | npm downloads and GitHub stars trends | | Recommendations | `devtune_get_content_gaps` | Read | Canonical content-gap signals with `signalStrength`, component metrics, and evidence | Each windowed tool accepts `windowDays` with fixed rolling windows and returns JSON data. Public MCP tools support only `30` and `90` day windows. Tool access depends on the project and permissions from your connection: * OAuth connections use the project you selected during setup and your DevTune role * API key connections use the project and permissions assigned to the key Write-capable tools, including `devtune_generate_action_brief`, require permission to manage actions for the selected project. `devtune_get_content_gaps` maps to `GET /api/v2/projects/{projectId}/content-gaps/list`. It exposes topic and prompt-cluster signals from the Actions system, including `signalStrength`, component metrics, and bounded evidence. Workflow state, briefs, interventions, and `opportunityScore` stay on the Actions tools. ## Tool Inputs | Tool | Inputs | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `devtune_get_visibility_summary` | `windowDays` (`30`, `90`), optional `platform`, optional `topicId` | | `devtune_get_competitive_position` | `windowDays` (`30`, `90`), optional `platform`, optional `topicId`, optional `grouping` (`daily`, `weekly`, `monthly`) | | `devtune_get_citation_analysis` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search` | | `devtune_get_top_citation_pages` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search` | | `devtune_get_top_citation_domains` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search` | | `devtune_get_citation_stats` | `windowDays` (`30`, `90`) | | `devtune_get_actions` | optional `status`, optional `surface`, optional `priority`, optional `channel`, optional `detailLevel` (`summary`, `context`), optional `page`, optional `pageSize` | | `devtune_get_action_brief` | `actionId` | | `devtune_generate_action_brief` | `actionId`, optional `briefStyle`, optional `allowPurchasedCredit` | | `devtune_get_traffic_summary` | `windowDays` (`30`, `90`), optional `domain` | | `devtune_get_adoption_metrics` | `windowDays` (`30`, `90`), optional `metric` (`github_stars`, `weekly_downloads`) | | `devtune_get_content_gaps` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize` | For `devtune_get_actions`, the most useful filters are: * `detailLevel`: `summary` or `context`; `summary` is default * `surface`: `recommendation` or `backlog` * `status`: `active`, `backlog`, `in_progress`, `blocked`, `done`, `canceled` * aliases: `open`, `completed`, and `dismissed` map to `backlog`, `done`, and `canceled` * `priority` and `channel` for narrower work queues Use `detailLevel: "context"` when the agent needs to understand why an action matters before deciding what to do. Context responses are capped to keep tools fast and predictable: up to 3 evidence blocks and 5 citation/source references per action, plus scores, metrics, brief readiness, and follow-up links. For all windowed MCP tools, `windowDays` accepts `30` or `90` and defaults to `30`. Citation top-list tools and content gaps use cursor pagination and return `nextCursor` when another page is available. Citation top-list tools support simple prefix search on URL and domain. `devtune_get_citation_stats` returns aggregate totals only and does not accept pagination or search inputs. Unsupported parameters such as `60`, `365`, `searchMode`, `classifications`, `severity`, arbitrary sort fields, and page-based pagination are rejected instead of being handled downstream. ## Which Tool Should I Use? | Goal | Tool | | --------------------------------------- | ----------------------------------------------------------------------------------------------------- | | See the account/project health snapshot | `devtune_get_visibility_summary` | | Diagnose citation/source movement | `devtune_get_top_citation_pages`, `devtune_get_top_citation_domains`, or `devtune_get_citation_stats` | | Compare primary brand vs competitors | `devtune_get_competitive_position` | | Find recommended work | `devtune_get_actions` | | Understand why a recommendation matters | `devtune_get_actions` with `detailLevel: "context"` | | Execute a recommendation | `devtune_get_action_brief` or `devtune_generate_action_brief` | ### Generating Action Briefs `devtune_generate_action_brief` is the MCP write operation for the Actions workspace. It takes the following inputs: | Parameter | Type | Description | | ---------------------- | ------- | ----------------------------------------------------------------------------------------------- | | `actionId` | string | UUID of the action to generate a brief for | | `briefStyle` | string | Optional style override. Use `best_fit` or an allowed content format such as `technical_guide`. | | `allowPurchasedCredit` | boolean | Optional consent to use purchased content credits if included monthly credits are exhausted. | When project content preferences are enabled, `briefStyle` must respect the project's allowed and blocked formats. Requests for blocked formats are rejected instead of silently generating the blocked style. The tool is idempotent for a ready or already-running brief: * If the brief is ready, it returns `status: "ready"` * If generation is already running, it returns `status: "generating"` * If generation can start, it queues background work and returns `status: "queued"` The response includes `success`, `message`, `actionId`, and, when queued, an `eventId`. Use `devtune_get_action_brief` afterward to poll for readiness and retrieve the generated markdown. ## Example Prompts Once connected, you can ask your AI agent questions like: * "What is my current share of voice across AI platforms?" * "Show me the competitive position trend for the last 30 days" * "Show my top citation pages and domains for the last 90 days" * "Summarize my aggregate citation stats for the last 30 days" * "List active recommendations for this project" * "Load the stored brief for action 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab and summarize the execution plan" * "Generate the action brief for action 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab" * "Show backlog items that are blocked or in progress" * "Which content-gap signals are strongest this month, and what evidence supports them?" * "How much traffic am I getting from AI chatbots?" ## Related Documentation * [**Authentication**](/api-reference/authentication) — API key and MCP OAuth authentication * [**Rate Limits**](/api-reference/rate-limits) — Request limits by plan tier * [**API Overview**](/api-reference/overview) — Full list of REST API endpoints