MCP setup — Cursor, Claude Code, Codex

The Linkworld platform exposes a Model Context Protocol (MCP) server at ${api_url}/api/mcp/sse. External vibe-coding clients — Cursor, Claude Code, Codex — connect over SSE and get on-demand access to:

list_skills — every skill the platform knows about, filterable by category
get_skill_docs — full reference for one skill (input + output schemas, scopes, risk level, markdown doc)
validate_manifest — exact same validator linkworld deploy uses
search_examples — grep through examples/ for patterns
lint_app — static checks across manifest + code (catches undeclared scopes, missing handlers, bot-noise omissions)
scaffold_app — generate a new app from a template, returning files for your IDE to write

This means: when your IDE’s LLM is about to call ctx.tools.call(...), it can ask the platform “what tools does graph_email actually return” instead of guessing.

1. Get a token

linkworld login --token <your-jwt>      # one-time, if not already done
linkworld mcp token                      # mints a 24h dev token

The token is bound to your tenant + user account; everything you read via MCP is what you have access to.

For shell-piping (CI / scripts):

TOKEN=$(linkworld mcp token --quiet)

2. Wire up your client

The fastest path: linkworld mcp config <client> prints a ready-to-paste JSON snippet plus the file path it goes in.

Cursor

linkworld mcp config cursor

Paste into ~/.cursor/mcp.json (or per-project .cursor/mcp.json):

{
  "mcpServers": {
    "linkworld": {
      "url": "https://app.linkworld.ai/api/mcp/sse?token=<TOKEN>",
      "transport": "sse"
    }
  }
}

Restart Cursor. The tools appear under the MCP integration panel. Try: “List the email-related skills available on Linkworld.”

Claude Code

linkworld mcp config claude-code

Save under ~/.config/claude/mcp.json (or wherever your Claude Code build looks for MCP configs):

{
  "mcp": {
    "linkworld": {
      "transport": "sse",
      "url": "https://app.linkworld.ai/api/mcp/sse?token=<TOKEN>"
    }
  }
}

Codex (and other Cursor-compatible clients)

The Cursor JSON shape works for most. If your client expects something custom, the connection details are:

Transport: SSE
URL: https://app.linkworld.ai/api/mcp/sse?token=<TOKEN>
Tools available: list_skills, get_skill_docs, validate_manifest, search_examples, lint_app, scaffold_app (plus the shared goal/artifact/project tools — see developer/reference/mcp-tools.md)

In-platform — same tools, `dx_*` prefix

The Linkworld web app’s /chat assistant has the same six tools without needing an MCP token — they’re registered as part of the mcp_dev skill. To avoid name collisions with assistant built-ins the prefix is dx_:

External IDE (this guide)	Linkworld /chat
`list_skills`	`dx_list_skills`
`get_skill_docs`	`dx_get_skill_docs`
`validate_manifest`	`dx_validate_manifest`
`search_examples`	`dx_search_examples`
`lint_app`	`dx_lint_app`
`scaffold_app`	`dx_scaffold_app`

Same impl, same return shapes — the only difference is the call site. Useful when you want to scaffold from /chat (“build me an app that posts daily KPIs”) without leaving the browser. Coding sessions running inside the platform’s compute VM also see the unprefixed names because they connect via the same MCP-SSE path as Cursor / Claude Code / Codex.

3. Verify the connection

In your IDE’s chat:

List the first 3 skills tagged "email".

The LLM should call list_skills(category="email") and return real data (graph_email, email_monitor, email_triage). If it hallucinates skill names that don’t exist or refuses tool calls, the MCP isn’t wired up — check the token + URL.

4. Token lifecycle

TTL: 24 hours. After that, mint a fresh one with linkworld mcp token and update the IDE config.
Storage: Cursor and most clients store MCP tokens plaintext in their config file (~/.cursor/mcp.json etc.). Treat that file with the same care as a SSH key — don’t commit it, don’t share screenshots.
Rotation: rotate at least monthly even if you haven’t hit TTL. Tokens are tenant-bound, so a leaked dev token reads (but doesn’t write) tenant data.
Revocation: today there’s no per-token revoke; rotating your account JWT (re-login) invalidates all your dev tokens at once.

5. Recommended workflow

The shape that works well for vibe-coding a Linkworld app:

"I want an app that watches my Slack mentions and drafts replies."

The LLM:

Calls list_skills(category="social") → finds nothing for Slack (we don’t ship a Slack skill yet) → tells you so directly instead of inventing one.
Suggests using a webhook from Slack into your app’s on_inbound handler.
Calls scaffold_app(slug="slack-mention-watcher", template="webhook-handler") → returns files.
Writes them into your project.
Calls validate_manifest to make sure scope/agent/runtime checks pass.
Calls lint_app once code is in place to catch cross-file issues.

You: linkworld deploy and linkworld upgrade slack-mention-watcher --tenant <yours> to ship.

The whole loop never asks you to copy-paste from docs.linkworld.ai.

6. Troubleshooting

“Token expired” → re-mint with linkworld mcp token.
“Connection refused” → the SSE endpoint is wss:// for some clients, https:// for others. Check your client’s MCP transport docs; the platform serves both.
“Tool not found” → the LLM might be calling a name it hallucinated. Ask it to call list_skills() first and verify.
Generated code calls nonexistent fields → ask the LLM to re-fetch get_skill_docs for the relevant skill. Output schemas are populated for graph_email, business_docs, report_pdf, whatsapp — others render with a ⚠️ marker.