MCP

Rankhog exposes its growth workflows through MCP. Growth execution requires an active or trialing product; authorized setup diagnostics and credit reads remain available when billing is inactive.

Use MCP when an AI client supports OAuth or bearer API keys and should call named tools instead of raw REST endpoints. The same capability registry backs MCP, REST, and the CLI.

Endpoint

https://api.rankhog.com/mcp

For local development, use your local API origin:

http://localhost:48738/mcp

OAuth discovery

curl https://api.rankhog.com/.well-known/oauth-authorization-server
curl https://api.rankhog.com/.well-known/oauth-protected-resource/mcp

Install in your client

Claude Code

claude mcp add --transport http rankhog https://api.rankhog.com/mcp

Claude (web and desktop): Settings, then Connectors, then Add custom connector. Paste https://api.rankhog.com/mcp.

Cursor: add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "rankhog": {
      "url": "https://api.rankhog.com/mcp"
    }
  }
}

VS Code

code --add-mcp '{"name":"rankhog","type":"http","url":"https://api.rankhog.com/mcp"}'

Any other MCP client that supports streamable HTTP and OAuth works with the same URL. Your client redirects through Rankhog sign-in and OAuth consent.

Growth workflows

MCP, REST, and CLI use the same capability registry and product services. The API reference lists every tool's exact inputs, outputs, and permissions.

post_opportunity_conversation_message accepts an optional answer containing the pending questionId and optional skipped flag. Send the answer text in message. A typed answer cannot consume a different pending question.

Agent recipe

List opportunities first. If one links to an approved action, execute it with idempotency, then poll status.

{
  "tool": "list_agentic_workspaces",
  "arguments": {}
}

{
  "tool": "list_opportunities",
  "arguments": {
    "organizationId": "org_...",
    "websiteId": "web_...",
    "managedRedditAccountId": "acct_...",
    "includeRecent": false,
    "limit": 50
  }
}

{
  "tool": "create_reddit_action",
  "arguments": {
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "actionType": "comment",
    "targetUrl": "https://www.reddit.com/r/SaaS/comments/examplepost/example/",
    "body": "We saw better activation after asking users for one setup action instead of showing a long checklist.",
    "riskSummary": "Contextual reply with no link and no promotional claim.",
    "idempotencyKey": "action-comment-2026-06-17-001"
  }
}

{
  "tool": "execute_reddit_action",
  "arguments": {
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "plannedRedditActionId": "act_...",
    "acknowledgement": "I understand this can publish or change Reddit state from the user's Reddit account.",
    "idempotencyKey": "execute-action-2026-06-17-001"
  }
}

The execute response is immediate:

{
  "status": "queued",
  "executionId": "job_...",
  "jobId": "job_...",
  "plannedRedditActionId": "act_...",
  "statusUrl": "/agent/v1/reddit-action-executions/status?executionId=job_..."
}

Poll until terminal:

{
  "tool": "get_reddit_action_execution_status",
  "arguments": {
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "executionId": "job_..."
  }
}

Terminal statuses are succeeded, failed, blocked, cancelled, and verification_required.

If status is verification_required, do not call execute_reddit_action again automatically. Reddit may already have accepted the write.

Credits

Posts, comments, replies, and warm-ups spend credits. Check what a product can spend before queuing work:

{
  "tool": "get_credit_balance",
  "arguments": {
    "organizationId": "org_...",
    "websiteId": "web_..."
  }
}

The response includes period (this product's monthly credits), bank (organization credits shared by every product), committed (held by queued actions), spendable, products, and costs. Omit websiteId to read the organization bank alone.

Page through the ledger with list_credit_ledger. Pass the previous nextCursor as cursor; it is null on the last page.

{
  "tool": "list_credit_ledger",
  "arguments": {
    "organizationId": "org_...",
    "websiteId": "web_...",
    "limit": 25
  }
}

execute_reddit_action fails with 402 agentic_insufficient_credits when the product cannot spend the action's cost. Buying credit packs, auto top-up, and admin adjustments are billing changes and are not MCP tools.

Scopes

Request the smallest set of scopes your client needs.

rankhog:read
product:write
strategy:write
warmup:write
growth:safety:write
reddit:rules:read
reddit:activity:read
browser:read
credits:read
conversation:write
reddit:draft:write
reddit:write:dangerous

Permissions and limits

Use an OAuth grant or an organization API key with the required permissions. Existing keys do not gain growth settings or safety permissions automatically. Bearer API keys work for clients that support custom authorization headers; OAuth discovery remains available for interactive clients.

Normal growth actions consume existing credits. Agents cannot buy credits, change billing or auto top-up, delete data, manage team/security settings, or change account-protection limits. get_credit_purchase_link lets a human complete checkout in Rankhog.

All mutations require an idempotency key. Repeating the same request returns its committed result; changing the input requires a new key. Poll returned job/execution ids for completion and use afterSeq for conversation updates. An uncertain submission must be verified before another send.

Safety scopes permit explicit incident resolution and review-prompt changes, but retain the existing evidence checks, revision checks, account grants, and execution fences. Enabling autopilot or starting warm-up additionally needs reddit:write:dangerous. Browser-backed operations use the customer's approved Rankhog transport; raw browser control is not exposed.

The retired approval and dangerous-post endpoints are removed. See the migration notes and the CLI for scripts.