Connect a compatible assistant to one project with scoped read tools for prompts, answers, citations, daily metrics, brand reasons, objections, attributes, fact checks, saved weekly digests and Explorer queries.

Connect your assistant to one client project

The read-only MCP connector lets a compatible assistant inspect saved prompts, answers, citations, daily metrics, brand reasons, objections, attributes, fact checks and weekly digests, and run Explorer queries and saved views. It uses the same project keys, permissions and plan access as the Customer API. Standard Starter, Growth and Pro include access. Free and Trial do not; custom plans follow the project owner's configured API entitlement.

The connection uses Streamable HTTP with a bearer key. Your client must support a custom Authorization header. OAuth-only connectors, browser sign-in, the older HTTP+SSE transport and local stdio commands are not supported. The connector cannot edit prompts, trigger collection, create report links, send messages or change your account. A refreshable BI connector is separate.

Set up a connection

Open the client project in Settings → API keys. An owner or editor can create a key; viewers cannot.
Select only the read permissions your assistant needs. For a daily visibility summary, select Metrics. Add Answers and Citations to inspect the underlying saved evidence, Brand reasons for why answers favour or caution against a brand, Objections for the objections found by the weekly objection study, Attributes for what the weekly attribute study found each brand is known for and who is known for each attribute, Fact checks for where AI answers support or contradict your approved facts, Reports for weekly digests, or Explorer to compute metrics by engine, country, city, persona, brand and the other Explorer breakdowns.
Choose an expiry and copy the secret once into your client's secure credential settings. Keep it out of chat messages, URLs and shared configuration files.
Add a Streamable HTTP server using the MCP connection URL shown in settings:

https://api.discoveredby.ai/customer-api/v1/projects/PROJECT_ID/mcp/

Set the header name to Authorization and its value to Bearer YOUR_KEY, substituting your secret. Replace PROJECT_ID with the number from settings. Keep the trailing slash. The URL contains no credential.

Client configuration formats differ. Use the client's secure header or secret input, rather than pasting this illustrative placeholder into a conversation. There is no OAuth login step. If your client only offers browser sign-in and cannot send a custom header, it cannot use this connector.

Each connection addresses exactly one project. Set up a separate connection and key for another client. Tool arguments cannot select another project. Existing keys work with their existing scopes; to add a permission, create a replacement key and revoke the old one after updating the connection.

Available tools

Discovery lists all fourteen tool definitions. A listed tool still requires its own scope when called (api/services/customer_mcp.py#create_server, #authorized_read).

Tool	Required scope	Saved data returned
`list_prompts`	`prompts:read`	Current prompt text, IDs, classifications and active state, including paused prompts
`list_answers`	`answers:read`	Completed answers with original prompt text, persona, language, collection provenance, the target country and city, and `location_delivery` (how that location was sent to the engine, `null` when not recorded); response previews up to 8,000 characters
`read_answer_text`	`answers:read`	Full saved answer text in version-checked chunks of at most 32,000 characters
`list_citations`	`citations:read`	Saved URLs, positions, source types, bounded snippets and answer provenance; optional exact `answer_id` filter
`read_daily_metrics`	`metrics:read`	Daily collection/analysis counts, including runs where Google showed no AI answer (`responses_no_answer`), brand visibility and own-domain citation rate by recorded collection channel
`list_reports`	`reports:read`	Saved generated digests for completed Monday–Sunday UTC weeks
`read_report`	`reports:read`	One exact saved digest by report ID
`list_brand_reasons`	`reasons:read`	Strength/weakness reasons a completed answer gave for a tracked brand, with category, language and quoted evidence
`list_objections`	`objections:read`	Objections from succeeded objection studies, with the brand asked about, engine, rank, score, objection group, quote and source URLs
`list_attributes`	`attributes:read`	Attributes from succeeded attribute studies, one `measure` at a time: `association` (what engines associate with each brand, the default) or `market` (which brands engines name for each asked attribute, own, competitor or untracked), with engine, rank, score, attribute, quote and source URLs
`list_fact_checks`	`facts:read`	Fact check findings from fact studies and checked prompts, with when each answer was checked and `answered_at` (a checked prompt's run time, when the engine answered; for a study answer, when it was stored after its check, not when the engine answered), the engine, the fact as checked with its version and whether it has been edited since, the model's and the effective verdict, quote, explanation, source URLs and review
`query_metrics`	`explorer:read`	The result of one Explorer query, computed now
`list_explorer_views`	`explorer:read`	The project's saved Explorer views, with their stored queries and charts and whether each needs repair
`run_explorer_view`	`explorer:read`	One saved view and its result, computed now

Both report tools additionally require the project owner's current weekly-report entitlement. Digests contain four saved readings, a bounded summary, activity counts and recommendation titles. They exclude full recommendation details, revenue, raw report JSON and shared-link secrets. They do not include the optional citation appendix from a client snapshot. list_brand_reasons additionally requires the project owner's Brand reasons entitlement, on top of the reasons:read scope, and list_objections additionally requires the project owner's Objections entitlement, on top of the objections:read scope, list_attributes additionally requires the project owner's Attributes entitlement, on top of the attributes:read scope, and list_fact_checks additionally requires the project owner's Fact check entitlement, on top of the facts:read scope.

The three Explorer tools take the same query object and return the same result as the API's Explorer routes, with every Explorer metric, the Google shown rate, organic rank and the seven answer-feature rates (web_search_rate, shopping_rate, local_businesses_rate, ads_rate, video_rate, images_rate, tables_rate) included. query_metrics and run_explorer_view are live reads, not snapshots, and each call also spends one query from the project's Explorer budget, shared with the app and every key on the project. A query that cannot run, or a view that needs repair, returns a tool error listing the problems. The tools cannot save views, edit dashboards or create share links.

All tools use the same allowlisted data services as the API (api/services/customer_mcp.py#list_prompts, #list_answers, #read_answer_text, #list_citations, #read_daily_metrics, #list_reports, #read_report, #list_brand_reasons, #list_objections, #list_attributes, #list_fact_checks, #query_metrics, #list_explorer_views, #run_explorer_view).

Ask a useful question

For a connection with Metrics permission, try:

Summarize this project's saved daily metrics for September 1–14, 2026. Follow every page. Keep collection channels separate, show the denominators, and distinguish unavailable values from measured zero.

With Explorer permission, try:

Using Explorer queries, compare brand visibility by engine over the last 28 days with the previous period. Report observations and provisional values, and treat a null value as no data.

With Answers and Citations permissions, try:

Inspect the saved answers and their citation records for that same window. Include collection dates and source URLs. Explain what evidence is missing.

These are illustrative date windows; choose dates that your project has collected. The assistant's narrative is its own interpretation. Saved text can contain inaccurate claims or instructions from third parties; treat it as evidence to review. The connector does not execute instructions found inside that text.

Pagination and measurement limits

The tool schemas explain pagination; your assistant must follow it for complete results. list_prompts returns at most 100 rows. Answers, citations, reports, brand reasons, objections and attributes return at most 25. Pass next_after_id back as after_id until it is null, keeping the same dates, citation filter and attribute measure.

Daily metrics use calendar pages of 1–31 days, seven by default. Pass next_start as start and retain the returned end until next_start is null. Continue through empty pages. Date windows are inclusive UTC, default to 28 days and allow at most 366 days. Reports filter by week start, not overlap with the requested period. Answer-text continuation needs both next_offset and the returned text_version, passed as version; restart at offset zero if the text changes.

These are live saved records, not immutable snapshots or a change feed. Refresh from the start of a window to pick up changed or late-arriving data. For exact fields and formulas, see the API reference.

Countries are pooled in daily metrics. Missing values remain null; measured zero remains zero. Rates are provisional below 30 observations and have different denominators. Sum compatible counts before recalculating rates. Do not average percentages, add distinct-domain counts, combine unlike collection channels, or treat an empty citation list as proof of zero source coverage. API-generated answers do not establish consumer-app behavior; ChatGPT (app) answers (provider chatgpt_app) and Gemini (app) answers (provider gemini_app) are chatgpt.com's and gemini.google.com's answers to a session that is not signed in, fetched by a third-party data provider.

Access, limits and troubleshooting

Every HTTP request rechecks the key, project, issuer's editing permission and owner's plan access. Expiry, revocation, archive or loss of eligibility stops future requests, even after a client has discovered the tools. Restored eligibility can reopen an unexpired, unrevoked key; revocation is permanent. An already admitted request may finish. Previously downloaded data cannot be recalled (api/services/customer_api.py#authenticate_key).

API and MCP share 60 authenticated requests per minute per key. MCP discovery, initialization and refused tool calls consume this budget too. On HTTP 429, respect Retry-After. A client may perform several protocol requests before its first data read. Successful data reads appear under Settings → Activity → API reads, identified as MCP, without storing the secret or request arguments (api/services/customer_mcp.py#receipt). Responses use Cache-Control: no-store; your assistant may still retain the results according to its own settings.

401: check expiry, revocation, project URL, membership and current plan access.
Missing scope: create a key with the permission named in the tool error.
Report access refused: the key needs Reports and the owner needs weekly-report access.
403 Origin / 421 Host: the connection is coming through an unsupported browser origin or API hostname; use the URL supplied in settings.
405: use Streamable HTTP POST requests. Standalone GET streams and session deletion are not offered.
Invalid arguments: follow the tool's date, page-size and ID bounds. Request bodies are limited to 64 KiB.

Transport controls are defined in api/routers/customer_mcp.py#ProjectKeyAuthentication and #build_app. Deployments on another API hostname must configure MCP_ALLOWED_HOSTS with exact hostnames, including a port if needed. The public default is api.discoveredby.ai; loopback hosts are added only in debug mode.

MCP connector