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
Library	`devtune_list_library`	Read	List Library items, Current-only by default
Library	`devtune_search_library`	Read	Hybrid-search Library items, Current-only by default
Library	`devtune_read_library_item`	Read	Read content, provenance, version state, and agent availability
Library	`devtune_upload_library_item`	Write	Upload text as a Library item or the next version of an upload
Library	`devtune_update_library_item`	Write	Change agent availability or detach/relink a Superseded version
Knowledge	`devtune_get_knowledge_profile`	Read	Read the Knowledge Profile and Pending, Approved, and Dismissed proposals
Knowledge	`devtune_update_knowledge_profile`	Write	Apply an immediate human-authored edit to one Knowledge Profile field
Knowledge	`devtune_review_knowledge_proposal`	Write	Approve, dismiss, or restore a Knowledge Profile proposal
Overview	`devtune_get_visibility_summary`	Read	Share of voice, presence rate, brand awareness, and citation counts
Overview	`devtune_get_timeline_events`	Read	Prompt-set changes, platform events, and detected citation-share changes that give context to trends
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	Actions with matched-cohort citation defence, a full-window execution fallback, 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
Execution	`devtune_get_prompt_actions`	Read	Find existing and suggested actions whose stored evidence includes a prompt
Execution	`devtune_create_prompt_action`	Write	Create or reuse an action from a prompt, optionally generating a brief
Diagnostics	`devtune_get_traffic_summary`	Read	LLM bot and referral traffic analytics by site or path
Ground truth	`devtune_get_traffic_platforms`	Read	Traffic by AI platform over a fixed window, with verified and failed bot-identity verdict sums
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	Topic, source, and brand gaps you do not own, over a fixed rollup window
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_audit_extraction`	Read	Matching stored section, nearby Markdown and extraction timestamp
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	Complete paginated landing-page evidence, engine breakdown, and Traffic overview
Ground truth	`devtune_get_recent_answer_fetches`	Read	Up to 20 latest hourly answer-fetch records in the selected UTC window; requires `traffic.read`
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 evidence- and credit-checked path
Agents	`devtune_list_dex_threads`	Read	Bounded recent Dex conversation threads and settled credits
Agents	`devtune_list_dex_handoffs`	Read	Pending specialist-agent handoffs for a Dex thread
Agents	`devtune_get_dex_events`	Read	Ordered, paginated Dex reply and lifecycle events
Agents	`devtune_start_dex_conversation`	Run	Start or idempotently reuse a metered Dex conversation
Agents	`devtune_send_dex_message`	Run	Steer an active Dex task or resume an expired thread
Agents	`devtune_rename_dex_thread`	Write	Rename a project-scoped Dex thread
Agents	`devtune_delete_dex_thread`	Write	Delete your private Dex chat after stopping live work; billing and audit records are retained
Agents	`devtune_decide_dex_handoff`	Run	Confirm or cancel a pending Dex specialist handoff
Agents	`devtune_decide_dex_memory`	Write	Save or dismiss a durable Dex memory offer

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, 30, 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 and Dex read tools require agents.read; starting, steering, renaming, deleting a Dex chat, or deciding a Dex handoff or memory offer requires agents.run. Deleting a chat requires a user-attributed API key owned by the chat creator. Existing API keys do not receive new scopes automatically. High-stakes target pages require explicit customer acknowledgement through acknowledgedHighStakes: true before an action can be created. User-locked pages remain unavailable. Creating an action from a prompt is free. Setting generateBrief: true reserves 2 content credits; the brief uses 1 to 2 credits depending on the research required. If generation cannot be queued, the action remains saved and the response returns briefStatus: "failed". Open that action to retry. New content is drafted for human review and is never published by this operation. Write-capable tools, including devtune_create_prompt_action and devtune_generate_action_brief, require permission to manage actions for the selected project.

Library and Knowledge permissions

Library and Knowledge tools use two explicit scopes:

library.read allows devtune_list_library, devtune_search_library, devtune_read_library_item, and devtune_get_knowledge_profile.
library.write allows devtune_upload_library_item, devtune_update_library_item, devtune_update_knowledge_profile, and devtune_review_knowledge_proposal.

library.write is a mutation grant. It permits the MCP client to upload project text, change whether a Library item is available to agents, detach or relink Superseded versions, directly edit the Knowledge Profile, and approve, dismiss, or restore profile proposals. A direct edit and an approval both change the target profile field; dismissing or restoring a proposal does not. Use devtune_update_knowledge_profile only for a deliberate human-authored edit. It applies immediately. System observations and agent learnings must remain proposals for review. API-key connections need the matching scopes on the key. Existing keys do not receive library.read or library.write automatically. OAuth connections include Library scopes for the selected project, but write tools still require the signed-in user to have project management permission. Library list and search tools return Current versions by default. Set includeSuperseded: true for deliberate historical retrieval. Results expose version state and numbering; a specific older item can be read by ID without being presented as current. Turning agent availability off does not hide an item from these UI, REST, or MCP reads. It prevents the item from being retrieved into managed-agent prompts. devtune_get_ai_referrals returns the same coverage as the REST Referrals endpoint in overview.referralCoverage: sessionsCurrent, sessionsPrevious, conversionsCurrent, and conversionsPrevious. Known counts remain visible when coverage is partial. Compare a metric across periods only when both of its flags are true, including engine and landing-page comparisons. devtune_get_content_gaps maps to GET /api/v2/projects/{projectId}/content-gaps/list. It returns the same measured topic, source, and brand rollup facts, coverage state, and offset/limit pagination as REST. Your own sources and brand are excluded, as are topics you hold at least half the citations on, because those are presence rather than a gap. Every count is a citation split into primary and competitor; the rollups hold no mention facts. Coverage reports availableDays, isPartial, and the asOfDate the window ends on, so a window that was rolled up from fewer days than requested says so. Use gapType or display-label search to narrow the list. Actions remain the source for workflow state, briefs, and interventions.

Tool Inputs

Tool	Inputs
`devtune_list_library`	optional `cursor`, optional `includeSuperseded`, optional `limit` (`1`-`100`, defaults to `25`)
`devtune_search_library`	`query`, optional `cursor`, optional `includeSuperseded`, optional `limit` (`1`-`100`, defaults to `25`)
`devtune_read_library_item`	`itemId`
`devtune_upload_library_item`	`title`, `content` (up to 500,000 characters), optional `replaceItemId`
`devtune_update_library_item`	`itemId`, optional `groundingEnabled`, optional `successorId` (UUID to relink; `null` to detach)
`devtune_get_knowledge_profile`	optional `cursor`, optional `limit` (`1`-`100`, defaults to `25`)
`devtune_update_knowledge_profile`	`targetField` (`positioning`, `products_services`, `tone`, `saved_instructions`), `value` (up to 12,000 characters)
`devtune_review_knowledge_proposal`	`proposalId`, `decision` (`approve`, `dismiss`, `restore`)
`devtune_get_visibility_summary`	`windowDays` (`30`, `90`), optional `platform`, optional `topicId`
`devtune_get_timeline_events`	`windowDays` (`30`, `90`); requires `visibility.read`
`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`, optional `sourceVertical`
`devtune_get_top_citation_domains`	`windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search`, optional `sourceVertical`
`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_prompt_actions`	`promptId`
`devtune_create_prompt_action`	`promptId`, `title`, `description`, optional `targetUrl`, optional `generateBrief` (defaults to `false`), optional `acknowledgedHighStakes`
`devtune_get_traffic_summary`	`windowDays` (`30`, `90`), optional `domain`, optional `pathPrefix` with `domain`
`devtune_get_traffic_platforms`	`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 `gapType` (`topic`, `source`, `brand`), optional `search`, optional `offset`, optional `limit` (`1`-`100`)
`devtune_get_page_metrics`	`windowDays` (`7`, `30`, `90`), optional `cursor`, `pageSize`, `category`, `sortKey`, `sortDirection`
`devtune_get_page_guard_rails`	optional `offset`, optional `pageSize`
`devtune_get_audit_summary`	`windowDays` (`7`, `30`, `90`)
`devtune_get_audit_findings`	optional `includeDismissed`, optional `offset`, optional `pageSize`
`devtune_get_audit_extraction`	`domain`, `pagePath`, `contentHash`, `inputHash`, `locator` from a section finding. Requires `audit.read`.
`devtune_get_google_eligibility`	optional `windowDays` (`7`, `30`, `90`), optional `evidenceLimit` (`1`-`25`, defaults to `10`); unavailable projects return `Resource not found`
`devtune_get_outcomes_ledger`	`windowDays` (`7`, `30`, `90`, `365`), optional `cursor`, `pageSize`, `status`
`devtune_get_ai_referrals`	`windowDays` (`7`, `30`, `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. Citation-defence opportunities in devtune_get_actions use successful executions for prompt/platform cells present in both 30-day windows. Their measurements include the matched execution totals, the cohort’s coverage of earlier citations, informational probe-day counts, and prompts or platforms present in only one window. DevTune withholds the loss claim when the matched cohort covers less than 60% of the earlier citation volume. 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 30. Citation top-list tools use cursor pagination and support simple prefix search on URL and domain. Content gaps use offset and limit pagination and support display-label search. 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
Browse the current Library catalog	`devtune_list_library`
Find relevant current or older material	`devtune_search_library`, then `devtune_read_library_item`
Add project text to the Library	`devtune_upload_library_item`
Control grounding or version links	`devtune_update_library_item`
Read company context and proposals	`devtune_get_knowledge_profile`
Apply a deliberate profile edit	`devtune_update_knowledge_profile`
Review a profile proposal	`devtune_review_knowledge_proposal`
See the account/project health snapshot	`devtune_get_visibility_summary`
Explain a change in a Visibility trend	`devtune_get_timeline_events`
Diagnose citation/source movement	`devtune_get_top_citation_pages`, `devtune_get_top_citation_domains`, or `devtune_get_citation_stats`
See which communities AI cites	`devtune_get_top_citation_domains` with `sourceVertical: "community"`
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`, `devtune_get_audit_extraction`
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 conversion events by AI engine	`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 evidence- and credit-checked dispatch path as the application, including evidence preflight, 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 topics, sources, and brands are cited most this month, and how much of that is mine?”
“Show page-level blind spots and guard rails for the last 30 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?”
“Search the current Library for our positioning guidance, then show the version and as-of date.”
“List Pending Knowledge Profile proposals and explain their provenance.”

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

Getting Started

Visibility

AI Demand

Act

Library & Knowledge

Outcomes

Projects & Settings

Account & Billing

Integrations

Server URL

Setup

Codex

Other OAuth MCP Clients

API Key

Claude Desktop

Cursor

Claude Code

REST vs MCP

Available Tools

Library and Knowledge permissions

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

​Library and Knowledge permissions

​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

Library and Knowledge permissions

Tool Inputs

Which Tool Should I Use?

Triggering a Managed-Agent Run

Generating Action Briefs

Example Prompts

Related Documentation