MCP server

#Endpoint and transport

Client set-up for each host is in Install and connect.

#Sign-in (OAuth 2.1)

A request to /mcp without credentials gets 401 with a challenge that points at the resource metadata:

WWW-Authenticate: Bearer realm="threefold", resource_metadata="https://api.threefold.eco/.well-known/oauth-protected-resource/mcp", scope="read"

Clients that implement the MCP authorization spec take it from there:

• Protected resource metadata (RFC 9728): /.well-known/oauth-protected-resource/mcp
• Authorization server metadata (RFC 8414): /.well-known/oauth-authorization-server
• Dynamic client registration (RFC 7591): POST /oauth/register
• Authorization code with PKCE, S256 only: /oauth/authorize, /oauth/token
• Refresh tokens (rotated) and revocation (RFC 7009): POST /oauth/revoke

Sign-in is an emailed link; the consent screen shows the requesting app, your account, a workspace selector and the scopes. Access tokens last an hour and refresh tokens 30 days, and both are stored hashed. Tokens map to the same workspace, scopes, plan and metering as API keys.

#Keyless

Add ?keyless=1 to the URL (or send X-Threefold-Keyless: 1) to use the read-only library tools without an account. Calls are capped per IP address per day (50 by default); past the cap the server answers 429 with Retry-After set to the next UTC midnight. Keyless responses carry X-Threefold-Next: sign in for the monthly allowance. Tools outside the keyless set (tracking apps, fresh pulls, AI analyses, anything that writes) are refused; sign in or use a key for those.

#Four tools

threefold exposes four tools over MCP (docs/agent-tools.md): app, market, check, and workspace. Each answers one of the person's questions across Brand (store listings and screenshots), Paid (ad libraries) and Organic (social posts) in a single call.

#Core principle

threefold returns evidence and criteria; the agent grades the user's material and cites the links.

• app: One app across stores (App Store, Google Play), pillars (Brand listing and screenshots, Paid ads, Organic posts, reviews) and markets. Key inputs: app (name or ID), markets (optional, up to 5), store (ios, play), focus (overview default, brand, paid, organic, reviews, changes), platform, format, since, cursor.
• market: One market and genre: top apps and how localised they are, longest-running ads, top posts, price points and local vocabulary. Key inputs: market, genre, like (optional reference app), vs (optional home market to compare against), store, focus (overview default, brand, paid, organic, pricing, language, launch), platform, format, cursor.
• check: Grade the user's own material for a target market. Key inputs: market, what (listing, screenshots, ad, name, website, repo, app), url (for what: website), listing fields (title, subtitle, keywords, promotional_text, description, screenshot_count), app (live app ID), name, genre, from (home market), store, and path (for what: repo on the local stdio server). threefold runs rule checks and returns criteria and reference examples; the agent grades the material.
• workspace: The user's apps, competitors per market and target markets, watches and changes, saved items and usage. Actions: get (default), set_apps, set_competitors, set_markets, watch, unwatch, changes, save, saved. Once set, app, market and check answer relative to the workspace.

#Results

Every result arrives as:

• Markdown digest (content[0].text): a concise summary under ~4,000 tokens with key numbers, top examples, direct citation links (store URL, ad library URL, post URL), a threefold.eco link for the user to view visually, and "Go deeper" follow-up lines.
• Image previews: up to 6 low-resolution previews per result in the order the digest refers to them.
• structuredContent: typed data matching the tool schema.
• _meta: cost_micro_usd, balance_micro_usd and data freshness.

Errors come back as JSON text plus _meta.error with the same fields as the HTTP error body, never as structuredContent.

#Scopes

On the Free plan, hosted MCP is available with read-only credentials; paid plans enable workspace updates and competitor tracking.