LinkIntel MCP: X Reference Briefs

1. 1

   Get a token

   Tokens map to exactly one LinkIntel profile and start with lnki_. Signing up issues one for you. To mint one by hand instead, use the admin API, authenticating with the Supabase service role key:

   $ curl -s -X POST https://www.getlinkintel.com/api/mcp/tokens     -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY"     -H "Content-Type: application/json"     -d '{"label":"hermes"}'

   The response carries the token once. Only a hash is stored, so it cannot be shown again. Put it in a password manager now.

   {
     "token": "lnki_...",
     "label": "hermes",
     "profile_id": "...",
     "note": "Store this now. Only a hash is kept, so it cannot be shown again."
   }

   See Managing tokens for listing and revoking. There is also a CLI, if you have the repository checked out:

   $ pnpm --filter @linkintel/private-linkedin-mcp token:new --label="hermes"

2. 2

   Add the server

   For Claude Code:

   $ 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

   Confirm it works

   Ask the agent to call prepare_content_brief with a topic and cohort you saved in setup. 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 allowance.

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 LinkedIn account. They only read analytics LinkedIn has already published to the profile owner.

Managing tokens

All three operations live at https://www.getlinkintel.com/api/mcp/tokens and take the Supabase service role key as a bearer. That is the right privilege level rather than a new one: anyone holding that key can already write to the tokens table directly, so this endpoint is convenience, not an escalation.

profile_id is optional while exactly one profile exists. Add a second and it becomes required, so a token can never silently land on the wrong profile.

$ curl -s https://www.getlinkintel.com/api/mcp/tokens     -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY"

$ curl -s -X DELETE https://www.getlinkintel.com/api/mcp/tokens     -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY"     -H "Content-Type: application/json"     -d '{"label":"hermes"}'

• 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.