MCP Server

DevTune exposes a Model Context Protocol (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:

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:

codex plugin marketplace add devtunehq/codex-plugins --ref main

After adding the marketplace:

Restart Codex
Open the plugin list
Install the DevTune plugin
Sign in when Codex opens the browser authorization flow
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:

{
  "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:

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

{
  "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:

{
  "mcpServers": {
    "devtune": {
      "type": "streamable-http",
      "url": "https://devtune.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dtk_live_YOUR_API_KEY_HERE"
      }
    }
  }
}

Claude Code

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
Ground truth	`devtune_get_404_demand`	Read	Project-scoped classified 404 Demand and sensor coverage
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
Ground truth	`devtune_get_page_metrics`	Read	Unified page metrics from the Audit rollup
Ground truth	`devtune_get_page_guard_rails`	Read	Paginated page guard-rail classifications
Ground truth	`devtune_get_audit_summary`	Read	Completed Audit summaries, pillars, checks, and outcome trend
Ground truth	`devtune_get_audit_findings`	Read	Paginated Audit findings
Ground truth	`devtune_get_google_eligibility`	Read	Fixed-window Google eligibility dimensions, transitions, and sitemap submission state
Ground truth	`devtune_get_outcomes_ledger`	Read	Outcomes ledger and scoreboard
Ground truth	`devtune_get_ai_referrals`	Read	AI-referral landing-page demand and Traffic overview
Agents	`devtune_list_agents`	Read	Roster and custom-agent display fields
Agents	`devtune_list_agent_runs`	Read	Managed-agent run status, timing, usage, and identity
Agents	`devtune_get_agent_run`	Read	One run and its bounded draft artifact after completion
Agents	`devtune_run_agent`	Run	Trigger or reuse a metered manual run through the existing dispatch path

Each windowed tool accepts only its documented fixed rolling windows and returns JSON data. Existing visibility tools use 30 and 90 days; the ground-truth tools mirror the application’s 7, 28, and 90 day windows, with 365 also available for the Outcomes ledger. 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

devtune_get_404_demand uses the existing traffic.read scope for API keys and OAuth connections. The other ground-truth tools require an API key with the corresponding pages.read, audit.read, outcomes.read, or referrals.read scope and are intentionally excluded from existing OAuth grants until OAuth supports explicit per-grant scope consent. Managed-agent read tools require agents.read, while devtune_run_agent requires agents.run. Existing API keys do not receive new scopes automatically. 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`
`devtune_get_traffic_summary`	`windowDays` (`30`, `90`), optional `domain`
`devtune_get_404_demand`	none
`devtune_get_adoption_metrics`	`windowDays` (`30`, `90`), optional `metric` (`github_stars`, `weekly_downloads`)
`devtune_get_content_gaps`	`windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`
`devtune_get_page_metrics`	`windowDays` (`7`, `28`, `90`), optional `cursor`, `pageSize`, `category`, `sortKey`, `sortDirection`
`devtune_get_page_guard_rails`	optional `offset`, optional `pageSize`
`devtune_get_audit_summary`	`windowDays` (`7`, `28`, `90`)
`devtune_get_audit_findings`	optional `includeDismissed`, optional `offset`, optional `pageSize`
`devtune_get_google_eligibility`	optional `windowDays` (`7`, `28`, `90`), optional `evidenceLimit` (`1`-`25`, defaults to `10`); unavailable projects return `Resource not found`
`devtune_get_outcomes_ledger`	`windowDays` (`7`, `28`, `90`, `365`), optional `cursor`, `pageSize`, `status`
`devtune_get_ai_referrals`	`windowDays` (`7`, `28`, `90`), optional `cursor`, optional `pageSize`
`devtune_list_agents`	none
`devtune_list_agent_runs`	optional `agentKey`, optional `cursor`, optional `pageSize`
`devtune_get_agent_run`	`runId`
`devtune_run_agent`	`agentKey`, `requestIdempotencyKey`, optional `instructions`, optional `modelId`

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. Guard-rail evidence includes googleEligibility only when the caller is entitled and the evidence has a fresh observation from a live exact-domain GSC source. It includes canonical, crawlable, indexed, and structuredData states (pass, fail, or unmeasured), together with observedAt and Google’s coverageState. For visibility, citation, content-gap, traffic-summary, adoption, and intelligence tools, windowDays accepts 30 or 90 and defaults to 30. Ground-truth tools accept the windows shown above and default to 28. 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 arbitrary ranges and undocumented filters 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`
Diagnose page-level ground truth	`devtune_get_page_metrics`, `devtune_get_page_guard_rails`
Review Audit findings and trends	`devtune_get_audit_summary`, `devtune_get_audit_findings`
Review Google eligibility	`devtune_get_google_eligibility`
Connect work to measured outcomes	`devtune_get_outcomes_ledger`
Inspect AI-referral demand	`devtune_get_ai_referrals`
Inspect missing-page demand	`devtune_get_404_demand`
Review agent availability and runs	`devtune_list_agents`, `devtune_list_agent_runs`, `devtune_get_agent_run`
Trigger an idempotent agent run	`devtune_run_agent`

Triggering a Managed-Agent Run

devtune_run_agent requires the explicit agents.run API-key scope and a caller-generated UUID in requestIdempotencyKey. Retrying with the same key reuses the existing run. The tool delegates to the same gated dispatch path as the application, including the ground-truth feature flag, model-catalog validation, autonomy rules, and credit reservation and settlement. It creates no external draft-write capability; completed draft artifacts are read with devtune_get_agent_run and approval remains in the application.

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

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?”
“Show page-level blind spots and guard rails for the last 28 days”
“Summarize open Audit findings and measured Outcomes for this project”
“List available agents and their recent runs”
“Run the Technical Auditor with idempotency key 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab”
“How much traffic am I getting from AI chatbots?”

Authentication — API key and MCP OAuth authentication
Rate Limits — Request limits by plan tier
API Overview — Full list of REST API endpoints

Getting Started

AI Search

Community Discourse

Adoption Metrics

Owned Content

AI Demand

Audit

Analytics

Actions & Outcomes

Agents

Projects

Account & Billing

Integrations

Server URL

Setup

Codex

Other OAuth MCP Clients

API Key

Claude Desktop

Cursor

Claude Code

REST vs MCP

Available Tools

Tool Inputs

Which Tool Should I Use?

Triggering a Managed-Agent Run

Generating Action Briefs

Example Prompts

​Server URL

​Setup

​Codex

​Other OAuth MCP Clients

​API Key

​Claude Desktop

​Cursor

​Claude Code

​REST vs MCP

​Available Tools

​Tool Inputs

​Which Tool Should I Use?

​Triggering a Managed-Agent Run

​Generating Action Briefs

​Example Prompts

​Related Documentation

Server URL

Setup

Codex

Other OAuth MCP Clients

API Key

Claude Desktop

Cursor

Claude Code

REST vs MCP

Available Tools

Tool Inputs

Which Tool Should I Use?

Triggering a Managed-Agent Run

Generating Action Briefs

Example Prompts

Related Documentation