dataforce-setup

Dataforce MCP setup

This skill is bundled with the dataforce Claude Code plugin. It's the one-shot configurator that wires the Dataforce MCP server into every MCP-speaking agent the user has installed locally.

What it does

1. Detect installed agents. Look for: ~/.claude.json (Claude Code), ~/.codex/config.toml (Codex), ~/.cursor/mcp.json (Cursor). Note which exist.
2. Confirm with the user via AskUserQuestion which agents to configure. Pre-select the ones detected.
3. Write the right config to each. Idempotent: if a dataforce entry already exists, update in place. Never duplicate.
4. Verify reachability. Run npx -y mcp-remote https://dataforce.simplicitylabs.io/api/mcp --version 2>/dev/null (or equivalent dry-run) to confirm the package fetches and the URL is reachable.
5. Report. Print a short summary of what changed and what the user should do next (open the agent, trigger a query, OAuth browser will pop).

Configurations to write

Claude Code

Already handled by the plugin's .mcp.json when the plugin is installed. This skill should NOT write to ~/.claude.json for Claude Code — that double-registers the server. Skip with a note: "Claude Code: handled by plugin manifest, no config write needed."

If the user has Claude Code installed but NOT via the plugin (rare — they ran the skill standalone), fall through and add to local scope:

claude mcp add dataforce -s user -- npx -y mcp-remote https://dataforce.simplicitylabs.io/api/mcp

Codex

Read ~/.codex/config.toml. If [mcp_servers.dataforce] block doesn't exist, append:

[mcp_servers.dataforce]
command = "npx"
args = ["-y", "mcp-remote", "https://dataforce.simplicitylabs.io/api/mcp"]

If it does exist, leave it (idempotent). Tell the user a backup at ~/.codex/config.toml.bak.<timestamp> was written before any change.

Cursor

Read ~/.cursor/mcp.json (create if missing). Merge into top-level mcpServers:

{
  "mcpServers": {
    "dataforce": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://dataforce.simplicitylabs.io/api/mcp"]
    }
  }
}

Preserve existing entries. Backup file the same way.

Fallback (unknown agent / user wants raw snippet)

Print both the JSON and the TOML forms, with a short note: "Drop the JSON into your agent's mcpServers config, or the TOML into the Codex-style equivalent. Both are equivalent — pick whichever your agent reads."

Verification step

After writing configs, run:

npx -y mcp-remote --help >/dev/null 2>&1 && echo "mcp-remote available"
curl -sS -o /dev/null -w "%{http_code}\n" https://dataforce.simplicitylabs.io/api/mcp

• mcp-remote should be on npx (lazy-installs on first use).
• The MCP endpoint should respond (probably 401 unauthenticated, which is the correct OAuth-prompt response — don't treat 401 as failure).

If curl returns a network error, surface it: "Can't reach dataforce.simplicitylabs.io — check your network or VPN. The MCP server is hosted on Cloudflare Workers."

After write — what to tell the user

Print exactly:

Dataforce MCP configured for: <comma-separated agents>.

Next step:
  1. Restart your agent (or open a new chat) so it picks up the new MCP server.
  2. Ask it something dataforce-y, e.g. "what were yesterday's top SKUs?"
  3. A browser tab will open the first time — log in via Clerk and click Allow.
  4. Token sits in ~/.mcp-auth/ and refreshes automatically.

Tools available once authorized:
  - get_orders
  - get_stock_summary
  - query_ads
  - cross_channel_summary

Backups (if any config files were modified):
  - <list of .bak.<ts> paths>

When the user wants to remove

If invoked with --remove or the user asks to uninstall:

• Claude Code: tell them to /plugin uninstall dataforce (don't try to remove the MCP manually from a plugin-managed entry).
• Codex / Cursor: delete the dataforce block from the relevant config, leave everything else alone, write a .bak.<ts> first.

Notes for the assistant

• Never write the OAuth token anywhere — that lives in ~/.mcp-auth/ and is managed by mcp-remote itself. This skill only writes the command that invokes mcp-remote.
• Don't ask for an API token. The bearer-token PAT flow (dfp_*) still works for power users, but it's not the default install path. If the user has a PAT and wants to use it instead of OAuth, point them at the dashboard at https://dataforce.simplicitylabs.io/settings/tokens — don't try to manage PATs from this skill.
• Idempotent. Re-running the skill should be a no-op if everything is already configured.
• Honour the user's existing config. Read, parse, merge — don't overwrite blindly.