///DEVELOPER

MCP Server

Articfly exposes a Model Context Protocol (MCP) server so you can drive article generation, brand brief lookups, and rewrites directly from MCP-compatible clients like Claude Desktop, Hermes Agent, OpenClaw, and Cursor. The endpoint speaks Streamable HTTP transport and authenticates with a bearer token you generate in your Articfly dashboard.

Prerequisites

›An active Articfly account with a subscription. Sign up at app.articfly.com. Article credits are consumed from the same monthly quota as the dashboard.
›An MCP client that speaks Streamable HTTP transport. Tested clients: Claude Desktop (current), Hermes Agent (hermes-agent@v2026.4.23), OpenClaw, Cursor. Stdio-only clients are not supported in v2.2.
›A bearer token generated from the MCP Tokens card in your Articfly dashboard settings (instructions below).

Generating a Token

Tokens are issued in the dashboard. The plaintext value is shown once at generation time, copy it immediately, Articfly stores only a hash.

Open the MCP Tokens card

In the Articfly dashboard, head to Settings. Scroll to the MCP Tokens card, between Application Preferences and Danger Zone.

Generate a new token

Click Generate token, give it a name you will recognize later (e.g. Claude Desktop laptop), and confirm. Articfly returns a token in the shape atk_<32 hex chars> with a default expiry of 90 days.

Copy the plaintext value

Copy the full token, including the atk_ prefix. This is the only time Articfly will display the plaintext. The token list will only show a masked preview from this point on. If you lose it, revoke and generate a new one.

Revoke any time

The same card lists every active token with last-used timestamps. Click Revoke to invalidate a token immediately. Revocation takes effect on the next request, no caching.

Connecting Your MCP Client

The Articfly MCP endpoint is POST https://api.articfly.com/api/mcp. Streamable HTTP transport, stateless per request, bearer auth. Below are working configs for the four tested clients. Replace atk_... with your token.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "articfly": {
      "type": "streamable-http",
      "url": "https://api.articfly.com/api/mcp",
      "headers": { "Authorization": "Bearer atk_..." }
    }
  }
}

Quit and relaunch Claude Desktop. The six Articfly tools will appear in the tool picker.

Hermes Agent

Add to your Hermes config.toml:

[mcp.servers.articfly]
url = "https://api.articfly.com/api/mcp"
type = "streamable-http"
headers = { Authorization = "Bearer atk_..." }

Tested against hermes-agent@v2026.4.23. Reload Hermes to pick up the new server.

OpenClaw

Create or edit .openclaw/mcp.json in your project root:

{
  "mcpServers": {
    "articfly": {
      "type": "streamable-http",
      "url": "https://api.articfly.com/api/mcp",
      "headers": { "Authorization": "Bearer atk_..." }
    }
  }
}

Same schema as Claude Desktop. OpenClaw discovers the server on workspace open.

Cursor

Create or edit .cursor/mcp.json in your project root (or the global Cursor config):

{
  "mcpServers": {
    "articfly": {
      "type": "streamable-http",
      "url": "https://api.articfly.com/api/mcp",
      "headers": { "Authorization": "Bearer atk_..." }
    }
  }
}

Cursor reloads MCP servers automatically when the config file changes.

Available Tools

Six tools are live in v2.2. They map onto the same Supabase records as the dashboard, every query is scoped to the user that owns the token.

`list_brand_briefs`

Returns every brand brief on your account with id, name, and a content snippet. Use this to pick the right brief id before calling generate_article.

`get_brand_brief`

Fetches a single brand brief by id with the full content body. Useful when you want the voice rules in your client context before drafting a topic list.

`list_articles`

Lists your articles with id, title, status, created_at, excerpt, mode, and source. Supports filters by status, source, brand_brief_id, and a limit (default 20, max 100).

`get_article`

Fetches a single article by id with the full content body. Poll this after generate_article until status is no longer processing.

`generate_article`

Kicks off a new article generation job and consumes one article credit. Required: topic (3-500 chars). Optional: keywords (max 20), instructions (max 5000), additional_info (max 2000), mode (standard / advanced), images_source (none / ai / stock / mix), header_source (none / ai_auto / stock), length (short / medium / long), brand_brief_id. Returns article_id, poll get_article until ready.

`rewrite_article`

Rewrites an existing article into a new version and consumes one article credit. Required: article_id. Optional: instructions, brand_brief_id. Returns rewrite_id. v2.2 has no get_rewrite tool yet, check the dashboard /rewriter page for results.

Security & Limits

›Tokens are stored as a sha256 hash in the api_tokens table. Articfly never logs the raw token. The first-time generate response is the only place the plaintext appears.
›Scope isolation. MCP tokens have scope mcp only, they cannot call any other Articfly endpoint. Frontend tokens cannot call /api/mcp.
›Tenant isolation is structural. Every service helper takes userId as its first argument and every Supabase query includes .eq('user_id', userId). Cross-tenant reads are impossible by construction.
›Rate limit: 60 requests per minute per token. The limiter keys Redis with a sha256 hash of the Authorization header, raw token bytes never touch Redis.
›Article credits: each call to generate_article or rewrite_article deducts 1 credit from your monthly quota (Page-One Protocol plan = 30 per month, plus any top-up packs).
›last_used_at updates fire-and-forget so token activity is observable in the dashboard. Auth failures emit a row to the security_events audit log.

Troubleshooting

"invalid_token" even though I just generated a token

Check three things. First, you copied the full atk_ prefix plus all 32 hex characters, 44 chars total. Second, there is no trailing whitespace or newline, shells often append a newline when you paste. Third, the token has not been revoked or expired, tokens default to a 90-day life. Open Settings → MCP Tokens in the dashboard and confirm the token is still listed and active.

"missing_auth" in the server response

Your client did not send the Authorization header. The most common cause is wrong config nesting, in Claude Desktop the headers block must be a sibling of type and url, not nested under either of them. Compare your config against the snippets above.

MCP client times out before getting a response

The Articfly MCP endpoint accepts POST only. GET, DELETE, and OPTIONS are rejected. Some MCP clients pre-flight with OPTIONS and treat the 405 response as fatal. Make sure your client treats 405 as benign and proceeds with the POST request.

generate_article called, get_article keeps returning "processing"

Article generation takes 60 to 120 seconds end to end. After 7 minutes the article-timeout-cron flips the status to failed and refunds the credit automatically. If you see processing persist past 10 minutes, open Dashboard → Jobs to inspect the queue and any error message attached to the job.

Billing