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
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 `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 one required input:

Parameter	Type	Description
`actionId`	string	UUID of the action to generate a brief for

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?”

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 Traffic

Analytics

Actions & Outcomes

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?

Generating Action Briefs

Example Prompts

Getting Started

AI Search

Community Discourse

Adoption Metrics

Owned Content

AI Traffic

Analytics

Actions & Outcomes

Projects

Account & Billing

Integrations

Documentation Index

​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?

​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?

Generating Action Briefs

Example Prompts

Related Documentation