Install and connect

threefold runs one remote MCP server over Streamable HTTP:

https://api.threefold.eco/mcp

Ways to authenticate

Method	How	Use it for
Browser sign-in	OAuth 2.1 with PKCE. Your client registers itself, you sign in with an emailed link and approve a workspace and scopes.	Chat apps, and coding agents when you would rather not store a key
API key	`Authorization: Bearer tf_live_…`, created in your workspace with the scopes you choose	Headless agents, CI, scripts
Sandbox key	`Authorization: Bearer tf_test_…`. Fixture data only, read-only, never charged.	Tests and CI wiring
Keyless	No credentials. Add `?keyless=1` to the MCP URL, or call REST routes without a key. Capped per IP address per day (50 by default).	Trying threefold out

Keys and tokens carry scopes: read, track, ingest, analysis, admin. Tools that need a scope your credential lacks are refused with 403. See Accounts and keys.

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.

Flag	What it does
`--client <name>`	`claude-code`, `codex`, `cursor`, `gemini`, `opencode`, `vscode` or `all` (default)
`--key tf_live_…`	Writes your API key into the entry as an `Authorization: Bearer` header
`--oauth`	Writes the URL only; your client signs in through the browser
`--url <url>`	Server URL (default `https://api.threefold.eco/mcp`)
`--dry-run`	Prints what would change and writes 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.

If npx threefold reports that the package does not exist, the npm package has not been published yet. Use the per-client settings below: they are exactly what the installer writes.

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.

Check that it works

Ask your agent: “Use threefold to see what wins in finance apps in Spain compared to Mexico.” It should call the market tool with { "market": "es", "genre": "finance", "vs": "mx" } and return a concise digest with citations and a link to view on threefold.eco (see Agent tools).

From a terminal, without a client:

curl -s -X POST "https://api.threefold.eco/mcp?keyless=1" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Agent skills

The threefold repository ships skills that teach an agent the workflows: use-threefold (overview of the four tools), market-entry-brief, localise-app, launch-in-market and competitor-watch. All skills follow the principle that threefold returns evidence and criteria while the agent grades the material.

Typed clients and REST

See SDKs and REST API.

Install and connect

#Ways to authenticate

#Clients

#One command for coding agents

#Claude Code

#Claude (claude.ai and Claude Desktop)

#ChatGPT

#Grok

#Cursor

#VS Code

#Codex

#Gemini CLI

#OpenCode

#Try it without an account

#Check that it works

#Agent skills

#Typed clients and REST