Alidade MCP
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| X_BEARER_TOKEN | No | X app-only bearer token used to fill in X post content. Optional. | |
| ALIDADE_API_KEY | Yes | Your Alidade workspace API key. Required. | |
| ALIDADE_MCP_URL | No | Override the upstream server. Optional. | https://api.alidade-ai.com/mcp |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Alidade provides competitive intelligence on organizations' social media messaging and digital marketing. All tools are scoped to the connected workspace (the one that owns the API key, or the one chosen when the OAuth connection was approved).
Typical workflow: call list_saved_searches to find a saved search (the recommended scope), then get_analytics with its id as savedSearchId. For ad-hoc scopes, look up entity IDs with find_entities and pass them as entityIds instead; get_entity resolves an entity ID you already hold (from a search result, a saved-search group, or channel-presence analytics) to its name, organization, and websites. search_mentions returns the individual posts behind the aggregates, and semantic_search_mentions finds posts by meaning from a natural-language query (both mentions tier only; each returned post counts against a monthly quota). search_ads lists the paid ads the scope's entities ran on Google, Meta, and LinkedIn (mentions tier; each ad counts against the same quota).
To persist a scope for reuse in the app and future calls, create_saved_search turns entity IDs from find_entities into a workspace saved search; update_saved_search and delete_saved_search modify it. Only team-editable workspace searches can be changed — Alidade-curated and view-only searches cannot. Prefer updating a search over deleting and recreating it, since readouts and bulletins reference searches and their groups by id.
All tool calls share one request rate limit (10 per minute by default) and each result reports the remaining allowance — pace calls accordingly and prefer one well-scoped call over many small ones. When a call returns TOO_MANY_REQUESTS, wait the indicated time before retrying.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_workspace_infoA | Identify the calling workspace: name, API access tier, how the call was authenticated, request rate limit, and monthly post-quota status. Useful as a first call to verify the connection works and see what access is available. |
| list_saved_searchesA | List the saved searches available to the workspace (workspace-shared plus Alidade-curated). A saved search bundles comparison groups of entities, a platform filter, a date range, and keyword filters — pass its id as savedSearchId to get_analytics or search_mentions. This is the recommended starting point for analytics questions. |
| get_saved_searchA | Get one saved search's configuration: comparison groups (with entity counts), platforms, date range, and keyword filters. To enumerate a group's member entities, use find_entities with savedSearchId and groupId. |
| list_organizationsA | List the tracked organizations (companies, advocacy groups, legislative and government bodies, etc.) the workspace can access. Each entity returned by find_entities belongs to one of these organizations. |
| find_entitiesA | Find tracked entities (brand accounts, executives, campaigns, etc.). At least one of search, organizationId, or savedSearchId is required — there is no unfiltered listing. Entity IDs can be passed to get_analytics and search_mentions via entityIds for ad-hoc scopes. |
| get_entityA | Get one tracked entity by ID: name, category, description, the organization it belongs to, and the websites on file for it (homepage, secondary site, blog, newsroom). Use it to resolve an entity ID seen in search_mentions results, a saved-search group, or channel-presence analytics. Per-channel account details come from get_analytics with the channel-presence metric. |
| get_analyticsA | Aggregated analytics for a scope of entities, broken down per comparison group. Scope with exactly one of savedSearchId (recommended — its groups, platforms, date range, and keyword filters all apply) or entityIds (ad-hoc, treated as a single group); the other parameters filter or override the scope. Metrics: post-volume (post counts + share of voice), engagement (likes/shares/replies), time-series (engagement over time), themes (messaging-theme breakdown; requires taxonomy), policy-issues, policy-entities (mentioned policymakers/bills with stance), network-analysis (mentioned people/orgs/events), tone-voice (writing tone + brand voice), brand-positioning, content-breakdown (by content type), channel-presence (per-entity accounts with follower counts). Content-analysis metrics report over the analyzed-post subset, so their denominators are smaller than raw post counts. |
| search_mentionsA | The individual posts behind the analytics numbers, with Alidade's content-analysis labels attached, newest first by default. Takes the same scope parameters as get_analytics, plus optional label filters (policyIssue, policySubissue, productTheme, csrTheme, campaignTheme, brandPositioning, mentionedEntity) that take arrays of label values matching the labels in get_analytics breakdowns: any value within a filter matches, and all filters must match. Requires the mentions API tier, and every returned post counts against the workspace's monthly post quota — keep pageSize small (default 25) and only paginate when needed. Posts from platform x omit text and engagement metrics per X API terms (Alidade's identifiers and analysis labels are still included); the result lists their X post IDs for lookup with an X API tool. |
| semantic_search_mentionsA | Find posts by meaning: embeds a natural-language query and returns the most similar posts (pure vector similarity, no keyword matching), most relevant first. Results carry the post text, metrics, and entity but not the content-analysis labels — use search_mentions for chronological listings, keyword filters, or labels. Scope with savedSearchId or entityIds like the other tools — a saved search's groups, platforms, and date range apply, but its keyword filters do not (fold important terms into query). Requires the mentions API tier, and every returned post counts against the workspace's monthly post quota — keep limit small (default 15). Posts from platform x omit text and engagement metrics per X API terms; the result lists their X post IDs for lookup with an X API tool. |
| search_adsA | The paid ads run by the entities in the scope, collected from the Google, Meta, and LinkedIn ad libraries, newest first by default: copy, link, creative URLs, run dates, reported impression and spend ranges, and a link to the ad's public ad-library page. Scope with savedSearchId or entityIds like the other tools; the date range keeps every ad whose run overlaps it, keyword filters match the ad's headline and body, and adPlatforms (google, meta, linkedin) narrows the ad libraries — a saved search's platform filter does not apply to ads. Requires the mentions API tier, and every returned ad counts against the workspace's monthly post quota — keep pageSize small (default 25) and only paginate when needed. |
| create_saved_searchA | Create a workspace saved search with manually curated comparison groups of entities (get entity IDs from find_entities). It appears in the app for all workspace members and can be used as savedSearchId in the other tools. Keyword filters accept either keywords/excludeKeywords or a booleanQuery — not both. To give each group its own keyword filter, set the keyword parameters on the groups instead (topicSearchMode perGroup). Dynamic (rule-based) groups can only be created in the app. |
| update_saved_searchA | Update a workspace saved search. Only searches with team_edit visibility can be modified — Alidade-curated and view-only searches cannot, and when connected via OAuth only the search's owner can change its visibility. Omitted fields are left unchanged. groups replaces all comparison groups: include each existing group's id (from get_saved_search) to preserve it, since readouts and bulletins pin group IDs and dropping a referenced group is refused. Providing any top-level keyword parameter replaces the whole keyword filter (empty arrays clear it) and switches to one shared filter. With per-group keywords (topicSearchMode perGroup), keyword parameters on a group replace that group's filter; existing groups (by id) without them keep their current keywords, new groups start with none, and when switching to perGroup they start from the shared filter. Searches with dynamic (rule-based) groups accept only name and description changes. |
| delete_saved_searchA | Permanently delete a workspace saved search with team_edit visibility (when connected via OAuth, only searches you own; a workspace API key can delete any team-editable search). Refused while readouts, bulletins, or chat projects still reference it — those references must be removed in the app first. Prefer update_saved_search when the goal is to change a search rather than remove it. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 13 tools
Every tool targets a distinct resource+action, and the two potentially confusable tools (search_mentions vs semantic_search_mentions) are explicitly contrasted in their descriptions as chronological/label-filtered vs pure vector similarity. Similarly find_entities, get_entity, and list_organizations have clearly separated roles, and the saved-search CRUD tools are unmistakable.
Almost all tools follow a predictable snake_case verb_noun pattern (get_analytics, create_saved_search, delete_saved_search, list_organizations). The only deviation is semantic_search_mentions, which prefixes a modifier before the verb, and the mix of find_/list_ for discovery verbs is slightly inconsistent though still readable.
13 tools is squarely in the well-scoped range, with each tool earning its place: discovery (list/get saved searches, organizations, entities), querying (mentions, semantic mentions, ads, analytics), and lifecycle management (create/update/delete saved search). No obvious redundancy or padding.
Saved-search lifecycle is fully covered (list/get/create/update/delete), and the analytics surface spans mentions, ads, entities, and multiple metrics. Minor gaps exist around app-only concepts referenced in descriptions (bulletins, readouts, chat projects, dynamic group creation) that have no API tools, but agents can work around these.