LinkIntel MCP: X Reference Briefs

1. 1

   Add the server (OAuth 2.1)

   OAuth 2.1 is the recommended path. Add the endpoint by URL; no token needed upfront. When the client makes its first request, it gets a 401 with authorization details. The browser opens for Google sign-in, checkout if you are new, and consent. After that, the client authenticates with the OAuth token it obtained.

   For clients without OAuth support, skip to step 2 (bearer token fallback).

2. 2

   Bearer token fallback (clients without OAuth)

   If your client does not support OAuth 2.1, get a bearer token instead. Go to https://www.getlinkintel.com/agent, create an account with Google, review and confirm the $39/month offer, then copy the private MCP handoff shown on /setup.

   Tokens start with lnki_ and map to exactly one profile.

   For Claude Code, add the server with:

   $ claude mcp add --transport http linkintel https://www.getlinkintel.com/api/mcp     --header "Authorization: Bearer $LINKINTEL_TOKEN"
   
   $ claude mcp list | grep linkintel   # expect: Connected

   For Claude Desktop and other clients that read a JSON config:

   {
     "mcpServers": {
       "linkintel": {
         "type": "http",
         "url": "https://www.getlinkintel.com/api/mcp",
         "headers": { "Authorization": "Bearer lnki_..." }
       }
     }
   }

   Prefer an environment variable over pasting the token into a config file that may end up in a backup or a screen share.

3. 3

   Authenticate and confirm

   If using OAuth 2.1, make your first MCP request. The client will get a 401 with authorization details and open the browser for sign-in. If using a bearer token, no additional auth step is needed. Either way, ask the agent to call list_references, then prepare_content_brief with one of the topic and cohort pairs it returns. A healthy response includes only stored, cited evidence:

   {
     "topic": "launch lessons",
     "cohort": "developer tools",
     "reference_posts": [{ "citation": { "platform": "x", "url": "https://x.com/..." } }],
     "limitations": ["Stored public-reference evidence only; it is not a reach prediction."]
   }

   To check without an agent, the endpoint speaks plain JSON-RPC over POST:

   $ curl -s -X POST https://www.getlinkintel.com/api/mcp     -H "Authorization: Bearer $LINKINTEL_TOKEN"     -H "Content-Type: application/json"     -H "Accept: application/json, text/event-stream"     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The block also reports days_stale, how much of the requested window actually has rows, and a plain-language warning when something is off.

Tools degrade rather than fail

Unique period members_reached is not stored for arbitrary date windows, because it can never be summed from daily figures. The tool returns every stored metric and sets reach to null with a reach_unavailable note. A null never becomes a zero, and a missing value is never compared against a real one to manufacture a delta.

"reach_unavailable": "Official unique period reach is not stored for arbitrary date windows...",
"metrics": {
  "impressions":     { "value": 10640, "previous": 9701, "delta": 939,  "percent_change": 9.7 },
  "members_reached": { "value": null,  "previous": null, "delta": null, "percent_change": null }
}

The logic lives in scheduled jobs. MCP requests only read the stored results, so a conversation can never consume the shared LinkedIn request budget.

The nightly job keeps stored data current. sync_now reports that policy without triggering a refresh.

Backfills are resumable

• Per-day windows are fetched newest first, so an interrupted backfill leaves the recent days complete.
• Days that already hold a value are skipped, so re-running only pays for what is still missing.
• If the budget runs out mid-run, everything already fetched is saved and the tool returns status: "partial". Nothing is thrown away.
• Rows where nothing was measured are never written, since their nulls would sum to zero and read as a genuine day of no activity.

Safety cap

75 / UTC day

LinkedIn limit

100 / member / day

Headroom

25 requests

3-day sync

~13 requests

Cost is asymmetric, and this drives the whole backfill design:

Because a 90-day pull of the core metrics costs only seven requests, long backfills are cheap for everything that matters. Windows longer than seven days skip the daily MEMBERS_REACHED series deliberately: it is non-additive and is never summed into a period total, so it is a diagnostic not worth one request per day.

What repeated use actually costs

Every MCP tool reads or writes LinkIntel storage only, so users can ask questions as often as they like without spending LinkedIn quota.

Scheduled jobs persist the metrics they collect. A post published minutes ago may stay pending until the next measurement run, and unique reach remains unavailable for arbitrary period windows rather than triggering a live API call.

• Only a SHA-256 hash is stored. A database leak yields no working credentials, and the raw token exists exactly once, at the moment it is issued.
• Unknown, malformed and revoked tokens all return the same 401. Nothing distinguishes them, so the endpoint cannot be used to discover which tokens are real.
• Revocation applies on the very next request. There is no cache to wait out.
• Every use updates a last-seen timestamp, so a token that is no longer in use is easy to spot and retire.
• Tokens are not passwords and grant no access to your X or LinkedIn account. They reach LinkIntel’s stored data for one profile and nothing else.

• LinkedIn reports roughly a one-day lag, and says aggregate reshares, reactions and comments can differ from its own UI.
• Period members_reached is fetched as a single official TOTAL window at tool time. Daily reach windows are kept only as a non-additive diagnostic and are never summed into period reach.
• Days backfilled in a window longer than seven days have no daily members_reached value by design. Period reach is unaffected.
• FOLLOWER_GAINED_FROM_CONTENT and PROFILE_VIEW_FROM_CONTENT currently return LinkedIn 500s. They are reported as non-blocking warnings and probed weekly, not on every sync.
• Per-post calls accept normal activity URLs and raw ugcPost or share URNs. Activity IDs are tried as ugcPost first and share on a 404. Posts are never enumerated or scraped.
• There is no official way to enumerate historical post URNs, which is why log_post exists: the content corpus is built from posts an agent explicitly registers.