MCP

Rankhog exposes paid agent capabilities through MCP.

Use MCP when an AI client supports OAuth 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

Client Config

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

Your client redirects through Rankhog sign-in and OAuth consent.

Tools

Core tools:

Get Agentic Actor: inspect the current actor and scopes.
List Agentic Workspaces: get organization, website, and managed account IDs.
Get Subreddit Rules: fetch verified or live subreddit rules.
Get Subreddit Activity: read recent activity from the durable Reactive source without changing collector scheduling.
Get Radar Coverage: read durable source freshness, overlap, backlog, and collector capacity without triggering a fetch.
Get Reddit Browser Status: check whether Desktop is ready.
Open Reddit URL: open an allowed Reddit URL in the paired Desktop browser.
Get Workspace Strategy: read the current Discovery and Radar state and shared inputs.
Start Discovery, Stop Discovery, and Run Discovery Now: control the proactive lane without changing Radar.
Set Radar Enabled: control the reactive lane without changing Discovery.
Update Strategy Inputs: replace shared keywords and verified community candidates.
List Opportunities and Get Opportunity: read actionable work, timing, public-safe evidence, typed evidenceSummary, blockers, and linked execution state. timeZone and nextTransitionAt are additive and may be absent from older responses.
Get Opportunity Conversation: read an opportunity's conversation timeline. Poll with afterSeq for new items.
Post Opportunity Conversation Message: send a plain text message to the opportunity agent. API keys can steer and ask, but confirming a Reddit write stays human-only.
Get Planned Reddit Action: inspect a planned action.
Create Reddit Post Draft: create a ready manual draft for a human to post.
Create Reddit Action: store a post, comment, reply, upvote, or join_subreddit action.
Execute Reddit Action: queue an approved stored action for Desktop execution.
Get Reddit Action Execution Status: poll queued, running, succeeded, failed, blocked, cancelled, or verification-required executions.
List Reddit Action History: page and filter every submitted, failed, blocked, cancelled, duplicate, or uncertain execution receipt for one paid workspace.
Get Reddit Action History: inspect submitted content, stable Reddit identity, lifecycle events, visibility and revision history, observations, and derived performance.
Get Control Pane Analytics Summary: read cached workspace analytics.
Get Job and List Planned Jobs: inspect background work.
Get Credit Balance: read period credits, the organization bank, committed and spendable amounts, per-product balances, and the cost table. Needs rankhog:read and organization membership only.
List Credit Ledger: page through every credit grant, purchase, refund, adjustment, and debit with its actor kind and the work it paid for. Needs credits:read. Member names and user ids are never included.
Legacy Dangerous Reddit Post Submit: compatibility path for old clients. New clients should use execute_reddit_action.

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 and approve_reddit_draft fail 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
strategy:write
reddit:rules:read
reddit:activity:read
browser:read
credits:read
conversation:write
reddit:draft:write
reddit:write:dangerous

Requirements

MCP calls require:

A signed-in Rankhog user.
Membership in the target organization.
An active or trialing website subscription.
The target managed Reddit account ID.
Rankhog Desktop when a browser-backed tool needs Reddit.

Credit reads are the exception: they need organization membership only, no subscription and no managed Reddit account, so a lapsed workspace can still see its balance and history.

Strategy mutations require a human OAuth actor, strategy:write, idempotency, and rate limits. Organization API keys remain read-only. Dangerous Reddit writes also require explicit acknowledgement, Desktop readiness, and the reddit:write:dangerous scope.

MCP execution respects the selected identity's Reddit account protection policy, including weighted rolling budgets and minimum spacing. MCP tools can report a delay or blocked action, but they cannot raise or remove the account's limits.

MCP clients never receive raw browser control. Rankhog Desktop receives versioned high-level workflows after server-side validation.

Next: use REST for HTTP automation or the CLI for scripts.

On this page