Connect threefold to your agent

MCP clients

#One command for coding agents

npx threefold mcp install

With no flags it writes a threefold entry for Claude Code, Codex, Cursor, Gemini CLI, OpenCode and VS Code. Pick one client with --client. Existing config files are copied to <file>.bak before they change, and running the command again changes nothing.

Without --key, the entry is just the server URL. The first request gets an OAuth challenge, and clients that support MCP authorization open a browser to sign in.

#Claude Code

claude mcp add --transport http --scope user threefold https://api.threefold.eco/mcp

To use an API key instead of browser sign-in:

claude mcp add --transport http --scope user threefold https://api.threefold.eco/mcp \
  --header "Authorization: Bearer tf_live_your_key"

#Claude (claude.ai and Claude Desktop)

Add a custom connector with the URL https://api.threefold.eco/mcp. Claude registers itself with threefold (OAuth 2.1 dynamic client registration), then opens threefold's sign-in page (an emailed link) and a consent screen where you pick the workspace and scopes. threefold is not in the Connectors Directory yet, so add it by URL.

#ChatGPT

In developer mode, create a custom app or connector with the URL https://api.threefold.eco/mcp and sign in when asked. The same OAuth 2.1 flow applies. threefold is not in the ChatGPT app directory yet.

#Grok

At grok.com/connectors, add a custom connector with the URL https://api.threefold.eco/mcp and sign in.

Chat-app sign-in follows the MCP authorization spec (protected resource metadata, PKCE with S256, dynamic client registration, refresh and revocation) and passes our in-process tests. We have not yet recorded a test in each chat app.

#Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "threefold": {
      "url": "https://api.threefold.eco/mcp"
    }
  }
}

Or open this install link in Cursor: cursor://anysphere.cursor-deeplink/mcp/install?name=threefold&config=eyJ0aHJlZWZvbGQiOnsidXJsIjoiaHR0cHM6Ly9hcGkudGhyZWVmb2xkLmVjby9tY3AifX0=

#VS Code

User profile mcp.json (macOS ~/Library/Application Support/Code/User/mcp.json, Linux ~/.config/Code/User/mcp.json, Windows %APPDATA%\Code\User\mcp.json):

{
  "servers": {
    "threefold": {
      "type": "http",
      "url": "https://api.threefold.eco/mcp"
    }
  }
}

#Codex

~/.codex/config.toml:

[mcp_servers.threefold]
url = "https://api.threefold.eco/mcp"

With a key, add http_headers = { "Authorization" = "Bearer tf_live_your_key" } to the same section.

#Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "threefold": {
      "url": "https://api.threefold.eco/mcp"
    }
  }
}

#OpenCode

~/.config/opencode/opencode.json:

{
  "mcp": {
    "servers": {
      "threefold": {
        "type": "remote",
        "url": "https://api.threefold.eco/mcp"
      }
    }
  }
}

For Cursor, VS Code, Gemini CLI and OpenCode, an API key goes in a headers object next to url: "headers": { "Authorization": "Bearer tf_live_your_key" }.

#Try it without an account

Library reads work without signing in, up to 50 requests per IP address per day. Point your client at:

https://api.threefold.eco/mcp?keyless=1

Keyless calls get the read-only library tools. Tools that track apps, pull fresh data or run AI analyses need you to sign in or use a key.

SDKs

Both clients are generated from the OpenAPI document, default to https://api.threefold.eco, and raise a typed error that carries the API's code, whose_error, retryable and hint. Use a tf_test_… key to run them against fixture data in tests.

#TypeScript

import { ThreefoldClient } from "@threefold/client";

const tf = new ThreefoldClient({ apiKey: process.env.THREEFOLD_API_KEY });

const comparison = await tf.compareMarkets({ from: "de", to: "jp", niche: "health-fitness" });
console.log(comparison.shared, comparison.localOnly);

Methods: libraryMeta, compareMarkets, searchApps, searchStore, topApps, getApp, marketBrief, b2bChecklist, searchPaidCreatives, searchOrganicPosts, trackApp, usage, plus get(path) and post(path, body) for any other route. Errors are ThreefoldError.

#Python

from threefold import ThreefoldClient

with ThreefoldClient(api_key="tf_live_your_key") as tf:
    comparison = tf.compare_markets("de", "jp", "health-fitness")
    print(comparison["shared"])

Methods: library_meta, compare_markets, search_apps, search_store, top_apps, get_app, market_brief, b2b_checklist, search_paid_creatives, search_organic_posts, track_app, usage, plus get and post. Needs Python 3.9 or later; depends on httpx and pydantic.

REST

Every tool is also an HTTP route. Library reads work without a key, up to the keyless cap:

curl "https://api.threefold.eco/api/compare?from=de&to=jp&niche=health-fitness"

With a key:

curl "https://api.threefold.eco/api/compare?from=es&to=mx&niche=finance" \
  -H "Authorization: Bearer tf_live_your_key"

The OpenAPI 3.1 document is at api.threefold.eco/openapi.json, and llms.txt lists every discoverable endpoint for agents. See the REST API docs and the API reference, or try calls in the Playground.

CLI

The same discover, describe and call loop from a terminal, against https://api.threefold.eco. Sign in once and every command uses the saved login; library reads also work without one.

npx threefold login                         # browser sign-in, refreshed automatically
npx threefold login --key tf_live_your_key  # or save an API key instead
npx threefold discover "compare meditation apps in DE and JP"
npx threefold schema compare_markets
npx threefold call compare_markets --from de --to jp --niche health-fitness

More in the CLI docs.