Skip to main content
The Agent API and MCP let authenticated AI clients and automations operate inside a Skayle organization. They expose the same approved, organization-scoped procedures used by the Skayle application through:
  • POST https://api.skayle.ai/mcp — MCP Streamable HTTP
  • GET https://api.skayle.ai/v2/tools — authenticated operation discovery
  • POST https://api.skayle.ai/v2/tools/:operation — authenticated operation execution
  • GET https://api.skayle.ai/v2/openapi.json — Agent API contract
The connection details are also shown in Settings → API & MCP.

​
Agent API versus CMS Content API

These are separate interfaces:
  • The Agent API and MCP use /v2 and /mcp. They let authenticated agents read and change Skayle data, run workflows, publish content, and manage integrations.
  • The Skayle CMS Content API uses /v1/{organizationId}. It is a read-only content delivery API for websites using Skayle CMS as their headless CMS.
Using Skayle CMS does not replace the Agent API. A frontend can retrieve content through /v1 while an AI client manages that content through MCP or /v2. Compare all developer interfaces →

​
What agents can access

The live operation catalog is authoritative and expands as Skayle adds features. It currently covers:
  • organizations, members, settings, and connector state;
  • profile, onboarding, billing/credit status, and API-key metadata;
  • content, topics, collections, taxonomies, and the Context Library;
  • generation, editing, media/avatar uploads, scheduling, publishing, and deletion;
  • article SEO/social metadata editing and duplicate-content consolidation;
  • dashboard, Search Console, and content analytics;
  • AI Search Visibility prompts, engines, competitors, analyses, and runs;
  • Site Audit status, results, performance, and runs;
  • member invitations, role management, Slack, GSC, and CMS integration operations;
  • organization-scoped agent audit records.
MCP clients receive one tool for each approved operation plus a catalog tool that reports its scope, risk level, and confirmation requirement. The catalog, not a hard-coded tool count, should be treated as the current contract. Skayle also audits the app router against this contract. Every app procedure must be explicitly exposed to agents or assigned to an intentional exclusion category. This prevents a newly added app capability from being silently left out of MCP. Authentication internals, cross-organization lifecycle actions, superadmin tools, billing mutations, OAuth callbacks, UI-only state, credential-secret creation, and internal diagnostics remain intentionally excluded. The Agent API can list and revoke existing API-key metadata, but creating a key stays in the authenticated Skayle settings UI because its secret is shown only once.

​
Search content by title, slug, or URL

The listManagerItems and listItems operations search titles, excerpts, slugs, canonical URLs, and external CMS URLs. You can pass either a bare slug or a full article URL; Skayle extracts the final URL path segment as an additional search term. This makes requests such as “find the content at https://example.com/blog/my-article” work even when the title does not contain my-article.

​
Connect an MCP client

Use this Streamable HTTP endpoint:
MCP clients that support OAuth can connect directly to that URL and complete the Skayle authorization flow.

​
Codex with OAuth

Codex detects Skayle’s OAuth metadata and opens the authorization flow.

​
Codex with an API key

Add the server and header to ~/.codex/config.toml:
Restrict the file to your user, restart Codex, and verify the server with codex mcp list. Never commit a live key to a repository.

​
Authentication

​
OAuth 2.1

MCP clients should connect directly to the /mcp URL. Skayle publishes OAuth authorization-server and protected-resource metadata under /.well-known/, supports PKCE and dynamic client registration, and shows a consent screen with the requested scopes. OAuth access and refresh tokens are bound to the selected organization. Membership is checked again on every agent request, so removing a user from an organization immediately removes access even if a token has not expired. Skayle advertises offline_access so compatible MCP clients receive a 30-day refresh token and can renew the one-hour access token during long-running tasks without reconnecting. Expired bearer tokens return an invalid_token challenge so clients can refresh automatically.

​
API keys

Create a key in Settings → API & MCP. Keys:
  • are shown once;
  • are hashed at rest;
  • expire after 90 days by default;
  • are bound to the organization that was active when they were created;
  • are rate limited to 1,200 requests per minute by default;
  • can be revoked from the same settings page.
When an API key exceeds its request limit, Skayle returns HTTP 429 with a Retry-After header. HTTP 401 is reserved for invalid, expired, or disabled keys, so MCP clients do not mistake temporary throttling for lost authentication. Use an API key as:
The MCP connection may be reported as “not logged in” by clients that use that label only for OAuth state. An X-API-Key connection is authenticated when Skayle accepts the header, even though no OAuth session exists.

​
Scopes

The operation catalog reports the exact scope for every operation. Stored connector passwords, OAuth tokens, API keys, cookies, private keys, and webhook secrets are redacted from all agent responses and audit summaries.

​
CMS connector behavior

Agent operations can inspect connector status, schemas, mappings, and supported taxonomies. With the required integration scope and explicit confirmation, they can also change connector configuration or run externally visible connector actions. Agents never receive stored CMS passwords, provider access tokens, application passwords, or other connector secrets. Connector calls continue to run through Skayle’s existing provider-specific validation and publishing logic. When an organization uses Skayle CMS, published content is available to its website through the separate /v1/{organizationId} Content API. When it uses WordPress, Sanity, Webflow, or Contentful, Skayle pushes content to that provider instead.

​
Calling the Agent API

Discover operations:
Call a read operation:
Create one topic directly without running AI topic generation:
createBlogTopic creates a pending topic in an enabled collection. Topic, primary keyword, angle, and collection are required; article type, writing style, and custom instructions are optional. Call a confirmation-required operation:
updateItem can edit the core article body and publishing state as well as h1, tldr, metaDescription, canonicalUrl, primaryKeyword, secondaryKeywords, Open Graph and Twitter titles/descriptions, schemaJsonLd, relatedArticles, and internalLinkSuggestions. For published items, the response also includes publishingWarnings covering missing or weak SEO fields, canonical mismatches, thin content, internal-link gaps, duplicate primary keywords, and likely title/intent cannibalization. Call the read-only validatePost operation before publishing to retrieve the same publishing warnings without changing the item. When content revalidation is configured, publishing, editing, unpublishing, or consolidating a content item sends its canonical URL to the connected website. The website can revalidate its content routes and notify IndexNow immediately; the XML sitemap remains the complete inventory for normal crawler discovery. For multiple organizations, configure CONTENT_REVALIDATION_WEBHOOKS as a JSON object keyed by organization ID, with webhookUrl and webhookSecret for each website. The legacy single-webhook environment variables remain supported. To consolidate duplicate content items in any enabled collection, call consolidateItems with one winnerId, one or more duplicateIds, and rewriteReferences and createRedirects set to true. Skayle rewrites stored links and references to the winner, drafts and unpublishes the duplicates, and stores permanent redirects from each old slug. Requests to an old slug through the CMS Content API return HTTP 308 to the winner. This destructive MCP operation requires content:delete, confirm: true, and a stable idempotency key. Publishing, scheduling, deletion, integration writes, and external analysis runs reject requests without confirm: true. Mutations should always provide a stable idempotency key so retries cannot create duplicate work.

​
Security boundaries

Agent access does not expose:
  • superadmin procedures;
  • impersonation or authentication internals;
  • raw SQL or unrestricted database access;
  • checkout, subscription cancellation, or plan mutation;
  • stored connector credentials or token material.
Every operation is executed through the existing oRPC procedure, including its validation, billing/entitlement checks, background-job behavior, and PostgreSQL row-level security. Each call creates an organization-scoped audit record that can be queried with listAgentAuditLog. Audit records include the operation, credential type, required scope, risk, status, request ID, timestamps, and sanitized input/result summaries. Audit reads and writes run in the same organization and user RLS context enforced for the rest of Skayle.