MCP Server API Reference
Connect AI agents to your inseeq organization using the Model Context Protocol (MCP).
Authentication
All requests require a valid API key passed as a Bearer token in the Authorization header.
Generate your API key in the inseeq app at Settings → API Key. The key is shown once at creation — copy and store it securely.
Authorization: Bearer inseeq_your_api_key_here
Your API key is scoped to your organization. All operations are automatically filtered to your org's data.
Endpoint
The MCP server accepts JSON-RPC requests over HTTP POST. It follows the Model Context Protocol specification with Streamable HTTP transport.
POST https://mcp.inseeq.com/mcp Content-Type: application/json Authorization: Bearer inseeq_your_api_key_here
The server operates in stateless mode — each request is independent. No session management is required.
Permissions
Your API key grants access to the following capabilities:
| Capability | Access |
|---|---|
| Read organization & brand profile | Allowed |
| List, read, create, update articles | Allowed |
| Change article status | Allowed |
| List, add, resolve comments | Allowed |
| Read context (knowledge base) | Allowed |
| Read performance metrics & goals | Allowed |
| Upload images | Allowed |
| Publish to CMS (WordPress, Webflow, etc.) | Not available |
| Write or delete context entries | Not available |
| Send email notifications | Not available |
Rate Limits
API keys are rate-limited to 60 requests per minute. If you exceed this limit, you'll receive a 429 Too Many Requests response. Wait and retry after a short delay.
Tools Reference
Each tool is called via the MCP protocol. Your MCP client handles the JSON-RPC framing — you just need to know the tool names and parameters.
Identity
inseeq_agent_whoami
Returns the authenticated agent's identity and organization binding.
No parameters
Organization
inseeq_get_organization
Get organization details by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
inseeq_get_brand_profile
Get the brand profile for an organization — voice, tone, vocabulary rules, and writing guidelines.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
inseeq_resolve_slack_channel
Look up which inseeq organization a Slack channel is mapped to.
| Parameter | Type | Required | Description |
|---|---|---|---|
| slack_channel_id | string | Yes | — |
| workspace_id | string | No | — |
Articles
inseeq_list_articles
List articles for your organization, optionally filtered by status.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
| status | string | No | Filter: draft, ready_to_write, writing, generating, in_review, approved, published |
| limit | number (1–100) | No | — |
| offset | number | No | — |
inseeq_get_article
Get article details by ID. Returns metadata by default; set include_content=true for full markdown and structured fields.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| include_content | boolean | No | Include full article content (default: false) |
inseeq_create_article
Create a new article in draft status.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
| title | string | Yes | — |
| description | string | No | — |
| meta_description | string | No | — |
| language | string | No | — |
| language_code | string | No | — |
| scheduled_publish_date | string (ISO 8601) | No | — |
| target_keyword | string | No | — |
| outline | string | No | — |
| cluster_topic | string | No | — |
| seo_title | string | No | — |
| wordpress_slug | string | No | — |
| focus_keyphrase | string | No | — |
inseeq_update_article
Update article content or metadata. Automatically creates a version snapshot before content changes.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| title | string | No | — |
| content | string | No | Full markdown content |
| intro | string | No | Introduction section |
| sections | array of {heading, content} | No | Structured article sections |
| sources | string | No | — |
| meta_description | string | No | — |
| featured_image_url | string | No | — |
| featured_image_alt_text | string | No | — |
| featured_image_title | string | No | — |
| featured_image_caption | string | No | — |
| featured_image_description | string | No | — |
| focus_keyphrase | string | No | — |
| seo_title | string | No | — |
| wordpress_slug | string | No | — |
| wordpress_category_ids | number[] | No | — |
| wordpress_author_id | number | No | — |
| scheduled_publish_date | string | null | No | — |
| target_keyword | string | No | — |
| outline | string | No | — |
| cluster_topic | string | No | — |
inseeq_update_article_status
Change an article's workflow status.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| status | string | Yes | draft, ready_to_write, writing, generating, in_review, approved, published |
| scheduled_publish_date | string (ISO 8601) | No | — |
inseeq_upload_article_image
Upload a base64-encoded image for an article. Returns the public URL and storage path. Max 5 MB.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| image_data | string | Yes | Base64-encoded image bytes |
| content_type | string | Yes | image/png, image/jpeg, image/gif, or image/webp |
| filename | string | No | Filename hint for extension |
inseeq_get_image_upload_url
Get a presigned URL for direct image upload. Upload the file binary via PUT, then call inseeq_finalize_image_upload.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| content_type | string | Yes | image/png, image/jpeg, image/gif, or image/webp |
inseeq_finalize_image_upload
Finalize an image upload after uploading binary to the presigned URL. Returns the public URL.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| storage_path | string | Yes | The storage_path returned by inseeq_get_image_upload_url |
Comments
inseeq_list_comments
List all comments for an article, organized into threads with unresolved count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
inseeq_poll_new_comments
Poll for new comments on an article since a given timestamp.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| since | string (ISO 8601) | Yes | Timestamp to poll from |
inseeq_add_comment
Add a comment to an article, optionally as a reply to an existing comment. Supports inline text selection.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| content | string | Yes | Comment text |
| parent_id | string (UUID) | No | Reply to this comment |
| selection_start | number | No | Character offset of selected text start |
| selection_end | number | No | Character offset of selected text end |
| selected_text | string | No | Cached copy of the selected text |
inseeq_resolve_comment
Resolve or unresolve a top-level comment thread.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| comment_id | string (UUID) | Yes | — |
| resolved | boolean | No | Default: true |
Context (Knowledge Base)
inseeq_get_context_index
Get the context index for your organization — a lightweight scan of available knowledge base sections and entries.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
inseeq_get_context
Get all context entries for your organization, optionally filtered by section.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
| section | string | No | Filter by section slug (e.g. "brand", "memory") |
inseeq_log_context_read
Log that the agent read a context file, for activity tracking.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
| path | string | Yes | Context file path, e.g. /context/visual/brand-kit.md |
| session_id | string | Yes | — |
| platform | string | Yes | "slack" or "web" |
Performance
inseeq_get_article_queries
Get stored search query data for an article. Aggregated from daily Search Console ingestion.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| start_date | string (YYYY-MM-DD) | Yes | — |
| end_date | string (YYYY-MM-DD) | Yes | — |
| sort_by | string | No | impressions, clicks, or position (default: impressions) |
| limit | number (1–200) | No | Default: 50 |
inseeq_get_article_performance
Get GA4 page-level metrics for an article over a date range.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| start_date | string (YYYY-MM-DD) | Yes | — |
| end_date | string (YYYY-MM-DD) | Yes | — |
| granularity | string | No | daily, weekly, or monthly (default: weekly) |
inseeq_list_portfolio_performance
Aggregate performance across all published articles for your organization.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
| period | string | Yes | last_7d, last_30d, or last_90d |
| sort_by | string | No | pageviews, trend, or position (default: pageviews) |
| limit | number (1–200) | No | Default: 100 |
inseeq_get_traffic_goals
Get traffic goals for an article with organization-level defaults as fallback.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
| article_id | string (UUID) | Yes | — |
inseeq_get_review_settings
Get the review configuration for your organization.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
inseeq_get_article_recommendations
Get existing optimization recommendations for an article.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string (UUID) | Yes | — |
| status | string | No | Filter: pending, accepted, rejected, applied, reverted |
| limit | number (1–50) | No | Default: 10 |
Skills
inseeq_get_enabled_skills
Get the list of enabled skills for your organization.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string (UUID) | Yes | — |
inseeq MCP Server API Reference
Need help? Contact peter@inseeq.com