Getting Started with the Swarmsight MCP Server

Swarmsight is a social-intelligence platform: you tell it what to watch for on Reddit, and it discovers, scores, and organizes the conversations that matter to you. The MCP server is what makes it special — it exposes the entire platform to your local AI agent (Claude Code, Claude Desktop, or any MCP-capable client), so you can run everything by simply talking to your agent.

This guide takes you from zero to a working setup: create an account, connect your agent, stand up the browser worker that does the discovering, and (optionally) wire in Reddit API access. It's written for both you and your agent — the agent-facing parts are choreographed turn by turn, so your assistant knows exactly when to act and when to wait for you.

What you'll need

• A Swarmsight account (free to create — note the approval step below).
• A local MCP-capable AI agent — e.g. Claude Code or Claude Desktop.
• The Swarmsight browser extension (Chrome or Firefox). This is required — it's how new Reddit comments are actually discovered.
• Optional but recommended: a Reddit app (client ID + secret) to unlock direct Reddit browsing and commenting.

Step 1 — Create your account

1. Go to https://www.swarmsight.app/signup and sign up with your email, a username, and a password.
2. After signing up you'll land on a "Your account is pending approval" screen. This is expected. Swarmsight is in limited access while pricing is finalized, so new accounts can sign up and log in but can't use the system until they're approved.
3. Wait for an operator to approve your account. Until then, every feature is gated and your agent's calls will return an ACCOUNT_PENDING_APPROVAL error. Once you're approved, log back in and continue.

Why the gate exists: it prevents accounts from running cost-incurring activity before a pricing plan is in place. It's a single flag on your account; once flipped, everything below works.

Step 2 — Generate your MCP API key

Your agent connects to the remote MCP server with a bearer key.

1. Log in at https://www.swarmsight.app/login.
2. Open Settings and expand the MCP API Key section.
3. Click Generate Key. A key of the form sk_mcp_… is created and shown once — copy it now. The page also shows a ready-to-paste connection config.

You can generate a key scoped to your personal account or to an organization. Keys live in your account settings; you can regenerate (invalidating the old one) or revoke at any time.

Step 3 — Connect your agent to the MCP server

Add Swarmsight to your agent's MCP configuration. For Claude Desktop / Claude Code this goes in your mcpServers block:

{
  "mcpServers": {
    "swarmsight": {
      "url": "https://www.swarmsight.app/mcp",
      "headers": {
        "Authorization": "Bearer sk_mcp_your_key_here"
      }
    }
  }
}

Restart your agent so it picks up the new server. Sessions auto-expire after 30 minutes of inactivity; your client re-connects automatically on the next call.

Agent turn 1 — verify the connection

Agent: call get_current_user to confirm the key works and report the connected account's email and role. → Wait for the user to confirm it's the right account before doing anything else.

Step 4 — Create a project

Everything in Swarmsight lives inside a project (monitors, results, knowledge base, notifications). You need one before you can monitor anything. Projects belong either to you personally or to an organization.

Agent: call list_projects. If none exist, call create_project with a name (e.g. "Product Marketing"). Report the new projectId. → Wait — you'll need that ID for the browser extension in the next step.

Step 5 — Install the browser extension (required)

The extension is the engine of Swarmsight: it runs in your real browser, performs the Reddit searches your monitors ask for, and sends the results back. No Reddit account or API key is needed for this — it works by reading public Reddit search pages, just like you would.

Install (Chrome)

Configure

1. Server URL: set this to https://www.swarmsight.app (the default is http://localhost:3000 — you must change it).
2. Worker Name: anything memorable, e.g. "Alice's MacBook".
3. Assignment IDs: paste your User ID (and/or Org/Project ID) so jobs for your account route to this worker. Your agent can fetch your User ID with get_current_user.
4. Leave Capabilities as Reddit + Comments. API Token is optional.
5. Tick Enabled. The worker now heartbeats and polls for jobs; you'll see its Worker ID, last heartbeat, and last poll in the popup.

Keep the browser running (an idle tab is fine) when you want discovery to happen — the worker uses your browser to do the searches.

Step 6 — Create your first monitor

A monitor is a saved set of keywords for a project. On a schedule, Swarmsight enqueues a search job for each due monitor; your extension picks it up, searches Reddit comments for those keywords, and returns matches, which are then scored and stored as "social things."

Agent: call create_monitor for the project with a few keywords (e.g. "self-hosted CRM", "open source analytics"). → Wait for the user to confirm the extension is enabled. Then poll list_social_things for that project to surface scored results as they arrive, and summarize the top hits.

Step 7 (recommended) — Set up a Reddit app

The browser extension covers comment discovery without any Reddit credentials. To let your agent browse Reddit directly (subreddits, specific posts, comment threads) and post comments/replies, add a Reddit app's client ID and secret.

1. Sign in to the Reddit account you want to use and go to https://www.reddit.com/prefs/apps.
2. Click "create another app…" Choose the web app type (this supports the redirect flow needed for posting; "script" is fine if you only ever want read-only browsing).
3. Set a name. For the redirect URI, enter exactly: https://www.swarmsight.app/api/reddit/auth/callback
4. Create the app. The client ID is the short string shown just under the app's name; the client secret is the longer "secret" value.
5. In Swarmsight Settings → Reddit Integration, paste the Client ID and Client Secret, and set a descriptive User Agent (e.g. Swarmsight/1.0 by u/yourusername). Save. (Your agent can also set these with update_user_settings or update_organization_settings.)
6. To enable commenting: click Connect Reddit Account to complete the OAuth flow (scope: submit). This stores a refresh token used by reddit_create_comment and reddit_reply_to_comment.

Heads-up (2025): Reddit tightened API access under its Responsible Builder Policy and largely disabled instant self-service app creation. If the "create app" form blocks you, you'll need to request access via Reddit's developer support form and wait for approval. Credentials created before that change continue to work.

What works with vs. without Reddit credentials

You can get real value out of Swarmsight before touching Reddit's API. Here's the exact breakdown, grounded in how the system actually works:

Works without any Reddit API credentials

• Comment discovery — monitors + the browser extension find new Reddit comments matching your keywords (the extension scrapes public search pages; no API key needed).
• Scoring & results — discovered items are scored and stored; browse them with list_social_things.
• Projects, monitors, post-monitors, notifications — full create/read/update/delete.
• Knowledge base — create entries, run RAG Q&A (chat_knowledge), and AI extraction (extract_knowledge).
• Account, organization, and worker management.

Requires a Reddit app (client ID + secret)

• Direct Reddit browsing — reddit_get_subreddit_posts, reddit_get_all_posts, reddit_get_post, reddit_get_comments. Without credentials these return: "Reddit API credentials not configured."

Requires Reddit OAuth (the "Connect" step, a refresh token)

• Posting — reddit_create_comment and reddit_reply_to_comment.

Always required

• The browser extension. It's the only path for automatic comment discovery — without it, monitors enqueue jobs that nothing picks up.

A note on new post discovery: Swarmsight's automatic discovery loop currently finds comments only. Post-monitors let you track a specific known post URL, but there is no automatic "find new posts matching keywords" job yet. You can still browse posts on demand with the reddit_get_* tools once Reddit credentials are configured.

The turn-by-turn agent walkthrough

Putting it together, here's the full choreography your agent can follow. Each step is "agent acts, then waits for you."

1. Agent: get_current_user → confirm the connection and report the account. Wait for the user to confirm approval status.
2. User: ensure the account is approved (log in; if "pending," wait for approval).
3. Agent: list_projects; if empty, create_project. Report the projectId and the user's User ID. Wait.
4. User: install the extension, set Server URL to production, paste the User ID into Assignment IDs, and tick Enabled.
5. Agent: create_monitor with the user's keywords. Wait for the user to confirm the worker is polling.
6. Agent: poll list_social_things; summarize the highest-scoring hits as they arrive.
7. User (optional): create a Reddit app and paste client ID/secret into Settings; click Connect to enable posting.
8. Agent (optional): use reddit_get_comments to pull full context on a hit, draft a reply, and — only with the user's go-ahead — reddit_reply_to_comment.
9. Agent: save useful findings with create_knowledge, then answer questions later with chat_knowledge.

What your agent can do — example one-liners

Once connected, here's a sampling of the 51 tools at your agent's disposal. Any of these is a single natural-language request away:

Projects & organizations

• "Spin up a new project called Competitive Intel."
• "List my projects and which org each belongs to."
• "Rename this project and mark it active."
• "Create an organization and make me the owner."
• "Update our org settings with these OpenAI and Reddit keys."
• "Delete the throwaway test project."

Monitors & discovery

• "Create a monitor for 'self-hosted CRM' and 'open source analytics'."
• "List all monitors on this project and their keywords."
• "Add 'data residency' to that monitor's search terms."
• "Show the highest-scoring comments discovered this week."
• "Find the social thing for this exact Reddit URL."
• "Manually log this comment as a result."
• "Pause discovery by deleting the noisy monitor."

Reddit (with credentials)

• "Browse the hot posts in r/selfhosted."
• "Show me what's trending on r/all right now."
• "Pull this specific Reddit post by URL."
• "Get the full comment thread for that post."
• "Draft a helpful reply to this comment (don't post yet)."
• "Post the approved reply to that comment."

Knowledge base

• "Save this insight to the knowledge base."
• "What are users saying about our pricing?" (RAG Q&A)
• "Extract structured facts from this support transcript."
• "List everything we know about competitor X."
• "Update that knowledge entry with the new figure."
• "Remove the outdated note."

Notifications, post-monitors & workers

• "How many unread notifications do I have?"
• "List my unread notifications and mark them read."
• "Track this specific Reddit post for new activity."
• "List the posts I'm tracking."
• "Show my connected workers and their last heartbeat."
• "List recent worker jobs and their status."
• "Enqueue a manual comment-search job."
• "Delete the stale worker entry."

Account & keys

• "Show my current profile."
• "Update my username."
• "Store my Reddit and OpenAI keys in my settings."
• "Generate an org-level MCP API key for our shared agent."

Troubleshooting

• Everything returns "pending approval." Your account isn't approved yet. Wait for approval, then log in again.
• The agent can't connect / 401. Re-check the Authorization: Bearer sk_mcp_… header and that the key wasn't regenerated. Generate a fresh key in Settings if needed.
• No results are appearing. Confirm (1) the monitor has keywords, (2) the extension's Server URL points at production, (3) your User ID is in Assignment IDs, and (4) the extension is Enabled and the browser is open.
• Reddit tools error with "credentials not configured." Add a Reddit client ID + secret in Settings → Reddit Integration.
• Commenting fails with "missing Reddit refresh token." Complete the Connect Reddit Account (OAuth) step.

You're set

That's the whole loop: create and get approved, generate a key, connect your agent, stand up the extension, and point a monitor at the conversations you care about — then let your agent surface, contextualize, and act on what it finds. Add Reddit credentials when you want direct browsing and the ability to reply. From here, just talk to your agent.