everyapp 0.2.2 → 0.3.0-rc.1

package/skills/everyapp/setup/providers.md

@@ -0,0 +1,353 @@
+<!-- generated: pnpm -C packages/cli docs:update writes this file from the built-in catalog (packages/sdk/src/internal/capabilities.ts, through packages/cli/src/docs/providersCatalog.ts). Edit the catalog, never this file: a test fails CI when it is stale. -->
+
+# Every catalog provider: its settings, its key and one check
+
+For a coding agent setting up a provider the Gateway's built-in catalog has. Each provider is a section under its id, so `setup/providers.md#<id>` points at it. Where the provider has a file of its own in this folder (its **Guide**), follow that file and read this section as its summary. Read [README.md](README.md) first: its rules hold here too, above all that a key never goes through the chat.
+
+A provider registered on one Gateway (`pnpm everyapp provider add`) is not in this file: `pnpm everyapp provider show <id>` prints its whole spec (its hint, settings, hosts, where the key comes from and its smoke request). The catalog has 23 providers: 2 API-key, 3 AI, 18 OAuth clients.
+
+The smoke request needs the key, so it runs where the key is: the person's terminal, with the variable they read in hidden, or through the app that uses it. It is one call that costs nothing (unless marked charged).
+
+## How a value gets in
+
+The three ways of [README.md](README.md), one line each (the rules, and the codes a failure carries, are there):
+
+- **The person types it**, in their own terminal in the `every-app` folder: `pnpm everyapp configure <app id>` (everything the app needs) or `pnpm everyapp secret set NAME` (one name), each value at a hidden prompt.
+- **A command produced it**: pipe it straight in, `… | pnpm everyapp secret set NAME --json`, so it is never shown.
+- **It is in an environment variable** the person read in hidden: `pnpm everyapp secret set NAME --from-env NAME --json`, or `pnpm everyapp configure <app id> --from-env --json`.
+
+## Providers
+
+| Id | Name | Kind | Settings | Guide |
+| --- | --- | --- | --- | --- |
+| [`dataforseo`](#dataforseo) | DataForSEO | API key | `DATAFORSEO_API_KEY` | [dataforseo.md](dataforseo.md) |
+| [`context`](#context) | Context.dev | API key | `CONTEXT_API_KEY` | [context.md](context.md) |
+| [`openai`](#openai) | OpenAI | AI | `OPENAI_API_KEY` | [openai.md](openai.md) |
+| [`openrouter`](#openrouter) | OpenRouter | AI | `OPENROUTER_API_KEY` | [openrouter.md](openrouter.md) |
+| [`workers-ai`](#workers-ai) | Workers AI | AI | `WORKERS_AI_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` (set by `everyapp setup`) | [workers-ai.md](workers-ai.md) |
+| [`linkedin`](#linkedin) | LinkedIn | OAuth client | `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET` |  |
+| [`facebook`](#facebook) | Facebook | OAuth client | `FACEBOOK_APP_ID`, `FACEBOOK_APP_SECRET` |  |
+| [`instagram`](#instagram) | Instagram | OAuth client | `INSTAGRAM_APP_ID`, `INSTAGRAM_APP_SECRET` |  |
+| [`threads`](#threads) | Threads | OAuth client | `THREADS_APP_ID`, `THREADS_APP_SECRET` |  |
+| [`youtube`](#youtube) | YouTube | OAuth client | `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET` | [google.md](google.md) |
+| [`tiktok`](#tiktok) | TikTok | OAuth client | `TIKTOK_CLIENT_ID`, `TIKTOK_CLIENT_SECRET` |  |
+| [`tiktok-business`](#tiktok-business) | TikTok Business | OAuth client | `TIKTOK_BUSINESS_CLIENT_ID`, `TIKTOK_BUSINESS_CLIENT_SECRET` |  |
+| [`reddit`](#reddit) | Reddit | OAuth client | `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET` |  |
+| [`pinterest`](#pinterest) | Pinterest | OAuth client | `PINTEREST_CLIENT_ID`, `PINTEREST_CLIENT_SECRET` |  |
+| [`discord`](#discord) | Discord | OAuth client | `DISCORD_CLIENT_ID`, `DISCORD_CLIENT_SECRET` |  |
+| [`slack`](#slack) | Slack | OAuth client | `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET` | [slack.md](slack.md) |
+| [`mastodon`](#mastodon) | Mastodon | OAuth client | `MASTODON_CLIENT_ID`, `MASTODON_CLIENT_SECRET`, `MASTODON_URL` |  |
+| [`kick`](#kick) | Kick | OAuth client | `KICK_CLIENT_ID`, `KICK_CLIENT_SECRET` |  |
+| [`twitch`](#twitch) | Twitch | OAuth client | `TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET` |  |
+| [`tumblr`](#tumblr) | Tumblr | OAuth client | `TUMBLR_CLIENT_ID`, `TUMBLR_CLIENT_SECRET` |  |
+| [`dribbble`](#dribbble) | Dribbble | OAuth client | `DRIBBBLE_CLIENT_ID`, `DRIBBBLE_CLIENT_SECRET` |  |
+| [`google-workspace`](#google-workspace) | Google (Gmail, Calendar, Search Console and Analytics) | OAuth client | `GOOGLE_WORKSPACE_CLIENT_ID`, `GOOGLE_WORKSPACE_CLIENT_SECRET` | [google.md](google.md) |
+| [`microsoft-365`](#microsoft-365) | Microsoft 365 (Outlook mail and calendar) | OAuth client | `MICROSOFT_365_CLIENT_ID`, `MICROSOFT_365_CLIENT_SECRET` | [microsoft-365.md](microsoft-365.md) |
+
+Gateway services have no key of this kind: `email`, `members` (sending mail is [email.md](email.md); the members list needs nothing).
+
+## API-key providers
+
+### dataforseo
+
+**DataForSEO** (`api_key`): SEO data: keyword metrics, live search results, domain rankings, backlinks.
+
+- **Settings:** `DATAFORSEO_API_KEY`
+- **What the key is:** The API login and password from API Access, as login:password (or that pair base64-encoded); the Gateway sends them as HTTP Basic. login:password, or its base64; never the dashboard sign-in password.
+- **Where the key comes from:** https://app.dataforseo.com/api-access
+- **API reference:** https://docs.dataforseo.com/v3/
+- **How it is sent:** `Authorization: Basic <DATAFORSEO_API_KEY>`, the value `login:password` base64-encoded (or sent as it is when it holds no colon: already encoded), to `api.dataforseo.com`, `sandbox.dataforseo.com` only, over https
+- **What apps may do:** access `read`; GET, POST on any grant; account-wide paths refused: `tasks_ready`, `tasks_fixed`, `id_list`, `errors`, `appendix/user_data`, `appendix/webhook_resend`
+- **Smoke request:** `GET https://api.dataforseo.com/v3/appendix/user_data`, expecting 200; free. Account-wide, so the Gateway refuses it for apps; run it from the person's terminal.
+- **Cost:** per call. A Google SERP $0.002 per 10 results; a Labs task $0.012 plus $0.00012 per item. The Gateway reads each answer's `cost` field (US dollars) into the usage counters.
+- **Rate:** not recorded
+- **Verified:** 2026-10-25, live
+- **Set it:** `pnpm everyapp secret set DATAFORSEO_API_KEY`, or `pnpm everyapp configure <app id>` for everything an app needs
+- **Guide:** [dataforseo.md](dataforseo.md)
+
+### context
+
+**Context.dev** (`api_key`): Scrapes and renders web pages, JavaScript included.
+
+- **Settings:** `CONTEXT_API_KEY`
+- **What the key is:** An API key from the Context.dev dashboard; the Gateway puts it on every call as a bearer token.
+- **Where the key comes from:** https://context.dev/
+- **How it is sent:** `Authorization: Bearer <CONTEXT_API_KEY>`, to `api.context.dev` only, over https
+- **What apps may do:** access `read`; GET, POST on any grant
+- **Smoke request:** none recorded
+- **Cost:** not recorded
+- **Rate:** not recorded
+- **Verified:** 2026-10-25, live
+- **Set it:** `pnpm everyapp secret set CONTEXT_API_KEY`, or `pnpm everyapp configure <app id>` for everything an app needs
+- **Guide:** [context.md](context.md)
+
+## AI providers
+
+### openai
+
+**OpenAI** (`ai`): OpenAI's models: responses, chat, embeddings, audio, images.
+
+- **Settings:** `OPENAI_API_KEY`
+- **What the key is:** A secret key from the API keys page; the Gateway puts it on every call as a bearer token.
+- **Where the key comes from:** https://platform.openai.com/api-keys
+- **API reference:** https://platform.openai.com/docs/api-reference
+- **How it is sent:** `Authorization: Bearer <OPENAI_API_KEY>`, to `api.openai.com` only, over https
+- **What apps may do:** list it under `providers` and call `/api/ai/openai/…` with `createGatewayFetch()`: POST to `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations`, `/v1/images/generations`, `/v1/images/edits`, `/v1/images/variations`, and more only where both `AI_PROXY_EXTRA_ROUTES` and the app's `ai.routes` allow it
+- **Smoke request:** none recorded
+- **Cost:** not recorded
+- **Rate:** not recorded
+- **Verified:** 2026-10-25, live
+- **Set it:** `pnpm everyapp secret set OPENAI_API_KEY`, or `pnpm everyapp configure <app id>` for everything an app needs
+- **Guide:** [openai.md](openai.md)
+
+### openrouter
+
+**OpenRouter** (`ai`): One key for many models, through OpenAI's API shape.
+
+- **Settings:** `OPENROUTER_API_KEY`
+- **What the key is:** An API key from OpenRouter's keys page; the Gateway puts it on every call as a bearer token.
+- **Where the key comes from:** https://openrouter.ai/settings/keys
+- **API reference:** https://openrouter.ai/docs
+- **How it is sent:** `Authorization: Bearer <OPENROUTER_API_KEY>`, to `openrouter.ai` only, over https
+- **What apps may do:** list it under `providers` and call `/api/ai/openrouter/…` with `createGatewayFetch()`: POST to `/api/v1/chat/completions`, `/api/v1/completions`, `/api/v1/responses`, `/api/v1/embeddings`
+- **Smoke request:** none recorded
+- **Cost:** not recorded
+- **Rate:** not recorded
+- **Verified:** 2026-10-25, live
+- **Set it:** `pnpm everyapp secret set OPENROUTER_API_KEY`, or `pnpm everyapp configure <app id>` for everything an app needs
+- **Guide:** [openrouter.md](openrouter.md)
+
+### workers-ai
+
+**Workers AI** (`ai`): Cloudflare's models, in the Gateway's own account.
+
+- **Settings:** `WORKERS_AI_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` (set by `everyapp setup`)
+- **What the key is:** A Cloudflare API token with Workers AI Read (the Workers AI page's prefilled token); the account is the Gateway's own.
+- **Where the key comes from:** https://dash.cloudflare.com/profile/api-tokens
+- **API reference:** https://developers.cloudflare.com/workers-ai/
+- **How it is sent:** `Authorization: Bearer <WORKERS_AI_API_TOKEN>`, to `api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai` only, over https
+- **What apps may do:** list it under `providers` and call `/api/ai/workers-ai/…` with `createGatewayFetch()`: POST to `/v1/chat/completions`, `/v1/embeddings`, `/v1/responses`
+- **Smoke request:** none recorded
+- **Cost:** not recorded
+- **Rate:** not recorded
+- **Verified:** 2026-10-25, live
+- **Set it:** `pnpm everyapp secret set WORKERS_AI_API_TOKEN`, or `pnpm everyapp configure <app id>` for everything an app needs
+- **Guide:** [workers-ai.md](workers-ai.md)
+
+## OAuth clients
+
+### linkedin
+
+**LinkedIn** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`
+- **Where the client comes from:** https://www.linkedin.com/developers/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/linkedin`, `https://<app>.<APP_BASE_DOMAIN>/integrations/social/linkedin-page`
+- **How it is sent:** POST `www.linkedin.com/oauth/v2/accessToken` (the client in the form body)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set LINKEDIN_CLIENT_ID LINKEDIN_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### facebook
+
+**Facebook** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `FACEBOOK_APP_ID`, `FACEBOOK_APP_SECRET`
+- **Where the client comes from:** https://developers.facebook.com/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/facebook`, `https://<app>.<APP_BASE_DOMAIN>/integrations/social/instagram`
+- **How it is sent:** GET/POST `graph.facebook.com/v<version>/oauth/access_token` (the client in the query)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set FACEBOOK_APP_ID FACEBOOK_APP_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### instagram
+
+**Instagram** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `INSTAGRAM_APP_ID`, `INSTAGRAM_APP_SECRET`
+- **Where the client comes from:** https://developers.facebook.com/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/instagram-standalone`
+- **How it is sent:** POST `api.instagram.com/oauth/access_token` (the client in the form body); GET `graph.instagram.com/access_token` (the client in the query)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set INSTAGRAM_APP_ID INSTAGRAM_APP_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### threads
+
+**Threads** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `THREADS_APP_ID`, `THREADS_APP_SECRET`
+- **Where the client comes from:** https://developers.facebook.com/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/threads`
+- **How it is sent:** GET/POST `graph.threads.net/oauth/access_token` (the client in the query); GET `graph.threads.net/access_token` (the client in the query)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set THREADS_APP_ID THREADS_APP_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### youtube
+
+**YouTube** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET`
+- **Where the client comes from:** https://console.cloud.google.com/apis/credentials
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/youtube`, `https://<app>.<APP_BASE_DOMAIN>/integrations/social/gmb`
+- **How it is sent:** POST `oauth2.googleapis.com/token` (the client in the form body)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set YOUTUBE_CLIENT_ID YOUTUBE_CLIENT_SECRET`
+- **Guide:** [google.md](google.md)
+
+### tiktok
+
+**TikTok** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `TIKTOK_CLIENT_ID`, `TIKTOK_CLIENT_SECRET`
+- **Where the client comes from:** https://developers.tiktok.com/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/tiktok`
+- **How it is sent:** POST `open.tiktokapis.com/v2/oauth/token/` (the client in the form body)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set TIKTOK_CLIENT_ID TIKTOK_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### tiktok-business
+
+**TikTok Business** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `TIKTOK_BUSINESS_CLIENT_ID`, `TIKTOK_BUSINESS_CLIENT_SECRET`
+- **Where the client comes from:** https://business-api.tiktok.com/portal/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/tiktok-business/`
+- **How it is sent:** POST `business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/token/` (the client in the JSON body); POST `business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/refresh_token/` (the client in the JSON body)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set TIKTOK_BUSINESS_CLIENT_ID TIKTOK_BUSINESS_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### reddit
+
+**Reddit** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET`
+- **Where the client comes from:** https://www.reddit.com/prefs/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/reddit`
+- **How it is sent:** POST `www.reddit.com/api/v1/access_token` (the client in the Basic header)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set REDDIT_CLIENT_ID REDDIT_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### pinterest
+
+**Pinterest** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `PINTEREST_CLIENT_ID`, `PINTEREST_CLIENT_SECRET`
+- **Where the client comes from:** https://developers.pinterest.com/apps/
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/pinterest`
+- **How it is sent:** POST `api.pinterest.com/v5/oauth/token` (the client in the Basic header)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set PINTEREST_CLIENT_ID PINTEREST_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### discord
+
+**Discord** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `DISCORD_CLIENT_ID`, `DISCORD_CLIENT_SECRET`
+- **Where the client comes from:** https://discord.com/developers/applications
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/discord`
+- **How it is sent:** POST `discord.com/api/oauth2/token` (the client in the Basic header)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set DISCORD_CLIENT_ID DISCORD_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### slack
+
+**Slack** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`
+- **Where the client comes from:** https://api.slack.com/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/slack`, `https://<app>.<APP_BASE_DOMAIN>/integrations/slack/callback`
+- **How it is sent:** POST `slack.com/api/oauth.v2.access` (the client in the form body)
+- **Scope sets an app lists:** `channels.read`, `users.read`, `users.email`, `messages.write`, `channels.join`, `channels.manage`, `files.write`, `user-channels.manage`
+- **Set it:** `pnpm everyapp secret set SLACK_CLIENT_ID SLACK_CLIENT_SECRET`
+- **Guide:** [slack.md](slack.md)
+
+### mastodon
+
+**Mastodon** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `MASTODON_CLIENT_ID`, `MASTODON_CLIENT_SECRET`, `MASTODON_URL`
+- **Where the client comes from:** `<MASTODON_URL>/settings/applications`
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/mastodon`
+- **How it is sent:** POST `<MASTODON_URL>/oauth/token` (the client in the form body)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set MASTODON_CLIENT_ID MASTODON_CLIENT_SECRET MASTODON_URL`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### kick
+
+**Kick** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `KICK_CLIENT_ID`, `KICK_CLIENT_SECRET`
+- **Where the client comes from:** https://kick.com/settings/developer
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/kick`
+- **How it is sent:** POST `id.kick.com/oauth/token` (the client in the form body)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set KICK_CLIENT_ID KICK_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### twitch
+
+**Twitch** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET`
+- **Where the client comes from:** https://dev.twitch.tv/console/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/twitch`
+- **How it is sent:** POST `id.twitch.tv/oauth2/token` (the client in the form body)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set TWITCH_CLIENT_ID TWITCH_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### tumblr
+
+**Tumblr** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `TUMBLR_CLIENT_ID`, `TUMBLR_CLIENT_SECRET`
+- **Where the client comes from:** https://www.tumblr.com/oauth/apps
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/tumblr`
+- **How it is sent:** POST `api.tumblr.com/v2/oauth2/token` (the client in the form body)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set TUMBLR_CLIENT_ID TUMBLR_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### dribbble
+
+**Dribbble** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `DRIBBBLE_CLIENT_ID`, `DRIBBBLE_CLIENT_SECRET`
+- **Where the client comes from:** https://dribbble.com/account/applications
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/social/dribbble`
+- **How it is sent:** POST `dribbble.com/oauth/token` (the client in the query)
+- **Scope sets an app lists:** none: the whole client is the grant
+- **Set it:** `pnpm everyapp secret set DRIBBBLE_CLIENT_ID DRIBBBLE_CLIENT_SECRET`
+- **Guide:** none beyond this section; the scopes to allow are in https://everyapp.com/docs/agent/repo/capabilities#oauth-clients
+
+### google-workspace
+
+**Google (Gmail, Calendar, Search Console and Analytics)** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `GOOGLE_WORKSPACE_CLIENT_ID`, `GOOGLE_WORKSPACE_CLIENT_SECRET`
+- **Where the client comes from:** https://console.cloud.google.com/apis/credentials
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/google/callback`
+- **How it is sent:** POST `oauth2.googleapis.com/token` (the client in the form body)
+- **Scope sets an app lists:** `identity`, `gmail.read`, `calendar.read`, `search-console.read`, `analytics.read`
+- **Set it:** `pnpm everyapp secret set GOOGLE_WORKSPACE_CLIENT_ID GOOGLE_WORKSPACE_CLIENT_SECRET`
+- **Guide:** [google.md](google.md)
+
+### microsoft-365
+
+**Microsoft 365 (Outlook mail and calendar)** (`oauth_client`): the Gateway holds the client and completes the token endpoints only; the app builds the authorize URL from the public client id and keeps people's tokens.
+
+- **Settings:** `MICROSOFT_365_CLIENT_ID`, `MICROSOFT_365_CLIENT_SECRET`
+- **Where the client comes from:** https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
+- **Redirect URIs to register:** `https://<app>.<APP_BASE_DOMAIN>/integrations/microsoft/callback`
+- **How it is sent:** POST `login.microsoftonline.com/common/oauth2/v2.0/token` (the client in the form body)
+- **Scope sets an app lists:** `identity`, `mail.read`, `calendar.read`
+- **Set it:** `pnpm everyapp secret set MICROSOFT_365_CLIENT_ID MICROSOFT_365_CLIENT_SECRET`
+- **Guide:** [microsoft-365.md](microsoft-365.md)

package/skills/everyapp/setup/remote-mcp.md

@@ -0,0 +1,199 @@
+# A remote MCP server as an MCP app
+
+Any remote MCP server that speaks Streamable HTTP (a docs search, a
+company's API, a SaaS tool's MCP endpoint) can become an MCP app of the
+Gateway's: `pnpm everyapp mcp add <url>` registers it, the Gateway serves its
+tools on its own `/mcp` to every member it is granted to as `<id>_<tool>`,
+holds the server's credential itself (a Gateway setting, never sent to an AI
+client), sends it only to the server's origin, and attributes, audits and
+counts every call like an app's. A read-only connection sees only the tools
+whose risk is `read`. At the end the person has the app on, its credential
+set and pinned to the server's origin, the people who need it granted, and
+one tool call through the Gateway's `/mcp` that worked.
+
+## Settings
+
+| NAME                                                                                  | required or optional                          | what it holds                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<ID>_MCP_TOKEN` (the app id upper-cased, `-` as `_`; `--secret` picks another name ending in `_MCP_TOKEN`) | required, unless the server takes no credential (`--auth none`) | What the server's docs call its API key, token or password. `--auth bearer` sends it as `Authorization: Bearer <value>`; `--auth header --header X-Api-Key` as `X-Api-Key: <value>`; `--auth basic` takes `user:password` and sends HTTP Basic. |
+
+The name is a Gateway setting like any provider key, set with
+`pnpm everyapp secret set <NAME>` (any name ending in `_MCP_TOKEN` goes to the
+Gateway; nothing else is accepted for it). When it is set, the CLI pins it to
+the origin of the MCP app that declares it (`https://treg.to` for
+`https://treg.to/mcp/`): the Gateway sends a credential only to the origin it
+was set for. A server re-pointed or re-added at another address needs its
+credential set again; only the operator (the Cloudflare login) can, so an
+owner or admin who changes an app in the Gateway never moves a credential.
+`mcp list` and `mcp show` say "needs setup" until it is set and pinned.
+
+`--auth oauth` is accepted and recorded, but the Gateway doesn't sign in to
+MCP servers with OAuth this week: such an app serves no tools ("OAuth: not
+supported yet"). If an OAuth server also takes an API key, add it with
+`--auth bearer` instead.
+
+## Costs and plans
+
+Every App charges nothing for an MCP app. The server's provider charges what
+it charges for its calls (its own plan and limits apply; read them on its
+site). Every forwarded call is counted in the organization's usage as
+`mcp:<id>`, and an owner or admin can cap an app's calls per month in Admin →
+Usage (off by default): past the cap a tool answers a tool error naming it
+until the next UTC month.
+
+## Only a person can
+
+- Create an account with the server's provider and accept its terms, when it
+  has any.
+- Create the API key or token on the provider's dashboard and type it at the
+  hidden prompt.
+- Decide who gets the app beyond the owners and admins (Admin → Apps → Manage
+  access), and whether a tool the server says is safe should count as a write
+  (you suggest; they decide).
+- Decide to replace a credential the Gateway already holds.
+
+## Before you start
+
+1. `pnpm everyapp status --json`: `data.installed` and `data.claimed` are
+   true; `data.gatewayUrl` is `https://<gateway host>`. Not installed, or no
+   owner: [gateway.md](gateway.md) first.
+2. The server's MCP address and how it authenticates, from its docs: an
+   `https://` URL (often ending in `/mcp`) that speaks Streamable HTTP. An old
+   HTTP+SSE-only endpoint (a separate `/sse` URL from 2024) isn't served. The
+   credential is usually an API key sent as a bearer token; some servers read
+   a header of their own (`X-Api-Key`); public servers take none. The
+   Gateway follows no redirects, so use the address the server answers at,
+   not one that redirects to it.
+3. `pnpm everyapp mcp list --json`: the server isn't added already (no entry
+   in `data.apps` with its `url`). The id is the domain's name, the label
+   before its suffix (`https://mcp.deepwiki.com/mcp` → `deepwiki`,
+   `https://treg.to/mcp/` → `treg`), or `--name <id>` (lowercase letters,
+   digits and hyphens, at most 32 characters); it is the tools' prefix, so
+   keep it short.
+
+## Steps
+
+One step per message: give the step, wait for the words it ends with
+("done", "I have it"), then the next.
+
+1. **You:** add it. `pnpm everyapp mcp add <url> --auth bearer --json` (or
+   `--auth header --header <name>`, `--auth basic`; nothing for a public
+   server), with `--name <id>` when the host name makes a poor id and
+   `--risk read` for a server that only reads and doesn't say so in its tool
+   annotations (`--risk write` treats every tool as a write). The app is on
+   at once for the person running it (when they are a member), the owners
+   and the admins. The `done` event's `data.id`, `data.key` (null for
+   `--auth none`; else the credential's `name` and whether it is `set` and
+   `bound` to the URL's origin) and `data.probe` (what one look at the server
+   from this machine found, without the credential) say what happened.
+   `PROVIDER_KEY_UNSET` means the credential comes next.
+   `REMOTE_MCP_PROBE_FAILED` and `REMOTE_MCP_WANTS_OAUTH` are warnings, never
+   refusals: a 401 with `--auth none` means the server wants a credential
+   (`pnpm everyapp mcp remove <id>`, then the same add with `--auth bearer`), a
+   redirect means another address, and "Couldn't reach" may be this
+   machine's network only (the Gateway fetches from Cloudflare).
+2. **Person:** the credential. They create the key on the provider's
+   dashboard, then, in a second terminal in the `every-app` folder:
+   `pnpm everyapp secret set <NAME>` (the name from step 1, for example
+   `pnpm everyapp secret set TREG_MCP_TOKEN`) and paste it at the hidden
+   prompt (for `--auth basic`, `user:password`). It ends with
+   `Set <NAME> on the Gateway`. When the person runs `mcp add` themselves at
+   a terminal, it asks `Set <NAME> now?` right after adding and, on yes, shows
+   the same hidden prompt (`secret set`'s own); No leaves it for `secret set`.
+   The README's other two ways work as for any `secret set` (a pipe into
+   `pnpm everyapp secret set <NAME> --json`, or the hidden read then
+   `--from-env <VAR>`); `mcp add <url> --auth bearer --from-env <VAR> --json`
+   takes the variable at the add itself, read before anything is written.
+   Wait for "done".
+3. **Person:** who gets it. The owners, the admins and whoever added it have
+   it already. Anyone else: Admin → Apps → the app's row → **Manage access**.
+   A member sees its tools after granting, in a client connected to the
+   Gateway (the next step).
+4. **Person:** connect an AI client to the Gateway if theirs isn't yet:
+   `claude mcp add --transport http everyapp https://<gateway host>/mcp`,
+   then `/mcp` → **everyapp** → **Authenticate** in Claude Code (other clients:
+   the same URL; mcp.md beside this folder, "Connecting a person").
+
+## Verify
+
+1. `pnpm everyapp mcp show <id> --json`: `data.status` is `"on"` (not
+   `"needs setup"`), `data.key.set` and `data.key.bound` are true and
+   `data.key.boundOrigin` is the URL's origin (all three skipped for
+   `--auth none`: `data.key` is null). `data.snapshot` is null until the
+   Gateway lists the tools, on the first request to its `/mcp` after the add
+   (or within the hour). From the checkout root,
+   `pnpm everyapp secret list --json` agrees: the name is in
+   `data.gateway.names`, its `data.gateway.mcpCredentials` entry has
+   `set: true`, and the app has left `data.apps` (it is listed there only
+   while it needs setup, with `setup.command` the `secret set` that sets it
+   up).
+2. One tool call through the Gateway: in the person's connected client, ask
+   for something the server does ("use <id> to …", or "list the tools <id>
+   offers"); the client shows a call to an `<id>_<tool>` tool and its
+   answer. On a Gateway with many tools the client may list them compactly:
+   then it finds them with `everyapp_search_tools` (`{ "app": "<id>" }`) and
+   runs one through `everyapp_call_read`. Then
+   `pnpm everyapp mcp show <id> --json` again: `data.snapshot.tools` is the
+   count listed and `data.tools[]` has each with its `name`, `serverName`,
+   `risk` and `source` (`hint`: the server's annotation; `default`: no
+   annotation, counted as a write; `app`: the `--risk` default;
+   `override`: yours).
+3. Risks, with the person: a tool the server marks read-only is callable by
+   every connection; one without a hint is a write (hidden from read-only
+   connections); one marked destructive is hidden from every client until
+   approvals exist. Change one with
+   `pnpm everyapp mcp tool <id> <tool> --risk read|write|destructive --json`
+   (`--risk annotations` drops the override), or leave a tool out entirely
+   with `--off`; the Gateway lists the tools again on first use.
+4. Logs, when a call fails: README's path (**Workers & Pages** →
+   `every-app-gateway` → **Observability** → **Live**). The remote proxy logs
+   each failed upstream call as `mcp.remote.upstream_failed` with the status
+   (never the credential), and a first-use pin as
+   `mcp.remote.credential_bound` (names from the design,
+   docs/design/2026-10-mcp-by-url.md; not checked against a live Gateway
+   here, unverified).
+
+## If it fails
+
+| error or symptom                                                       | meaning                                                                                                     | what to do                                                                                                                         |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `SECRET_VALUE_REQUIRED` from `secret set --json`                       | Nothing was piped and there is no terminal to prompt in                                                     | One of the README's three ways: the person's own terminal, a pipe, or `--from-env`                                                  |
+| `SECRET_EMPTY`                                                         | The `--from-env` variable is empty or not exported in that shell (from `mcp add --from-env`, nothing was added) | The hidden read (README's third way) in that same terminal first, then rerun                                                     |
+| `REMOTE_MCP_URL_REFUSED`                                               | Not `https://`, an IP address, the Gateway's own host or app domain, or a provider the Gateway holds a key for | The server's own MCP address, by host name, over https                                                                              |
+| `REMOTE_MCP_EXISTS`                                                    | That id is an MCP app already                                                                               | `pnpm everyapp mcp show <id>`; another address is `mcp remove <id>` then `mcp add` again, or another `--name`                       |
+| `REMOTE_MCP_SECRET_TAKEN`                                              | Another MCP app at another origin uses that credential name                                                 | `--secret <OTHER>_MCP_TOKEN`: one credential name per origin                                                                        |
+| `REMOTE_MCP_INVALID`                                                   | A bad id, risk, header or credential name, or flags that say two things                                     | As the message says                                                                                                                 |
+| `PROVIDER_APP_UNKNOWN`                                                 | The id isn't an MCP app here                                                                                | `pnpm everyapp mcp list` for the ids                                                                                                |
+| `REMOTE_MCP_SECRET_BOUND_ELSEWHERE` from `mcp add`, or `needs setup` in `mcp list` or `mcp show` with the key set | The credential is pinned to another origin (`data.key.boundOrigin`): it was set for an earlier server | `pnpm everyapp secret set <NAME>` again (Steps 2)                                                                  |
+| `REMOTE_MCP_TOOL_NOT_LISTED` from `mcp tool`                           | The tool's name isn't in the last listing: the override was kept under that name, as the server's           | `pnpm everyapp mcp show <id>` for both names, then `mcp tool` with the right one                                                    |
+| `REMOTE_MCP_SECRET_UNDECLARED` from `secret set`                       | No MCP app declares that name (a typo, or set before `mcp add`)                                             | Check the name with `mcp show <id>`; `mcp add` first                                                                                |
+| `REMOTE_MCP_WANTS_OAUTH`                                               | The server wants OAuth, which the Gateway doesn't do yet                                                    | If it also takes an API key: `--auth bearer` and set the key; otherwise it can't be served this week                                |
+| `REMOTE_MCP_GATEWAY_OUTDATED`                                          | The Gateway predates MCP apps by URL                                                                        | `pnpm everyapp update`, then Verify                                                                                                 |
+| `data.snapshot.status` `error`, `lastError` naming 401                  | The server rejected the credential                                                                          | A fresh key from the provider, `secret set` again, then `pnpm everyapp mcp refresh <id>`                                            |
+| `lastError` naming a redirect or a timeout                             | The address redirects, or the server is slow or down                                                        | The address it redirects to (remove, add again); a slow server: retry later                                                        |
+| The tools changed on the server, not on the Gateway                    | The Gateway's snapshot is up to an hour old                                                                 | `pnpm everyapp mcp refresh <id>`                                                                                                    |
+| A tool is missing for one person only                                  | Their connection is read-only (write tools hidden), or they weren't granted the app                         | Admin → Apps → Manage access; a read & write connection                                                                            |
+
+## Rerun, rotate, remove
+
+- **Rerun.** `mcp add` refuses an id that exists (`REMOTE_MCP_EXISTS`), so a
+  rerun starts from Verify. `secret set` replaces; `mcp tool` and
+  `mcp refresh` can run again.
+- **Rotate.** A new key on the provider's dashboard, then Steps 2 again: the
+  Gateway uses the new value on its next request. A value that went through
+  the chat is compromised: rotate it.
+- **Off, and back on.** `pnpm everyapp mcp off <id> --json` stops serving it
+  and keeps everyone's access, tokens and the snapshot;
+  `pnpm everyapp mcp on <id> --json` serves it again at once.
+- **Remove.** `pnpm everyapp mcp remove <id> --json`: a tombstone, with
+  everyone's access, its tokens and its place in AI connections gone (adding
+  it again starts fresh). The credential and its pin stay;
+  `pnpm everyapp secret unset <NAME> --json` removes both (it asks; with
+  `--json` add `--yes` only once the person said so). Then revoke the key on
+  the provider's side.
+
+## Sources
+
+- docs/design/2026-10-mcp-by-url.md (the remote block, the credential family and its pin, the proxy, the defaults taken)
+- In code: `packages/sdk/src/internal/remoteMcp.ts` (the URL, id, auth and risk rules: `remoteMcpUrlProblem`, `remoteMcpIdFromUrl`, `remoteToolRisk`), `packages/sdk/src/internal/gatewaySettings.ts` (`isRemoteMcpSecretName`: any name ending in `_MCP_TOKEN` is the Gateway's), `packages/sdk/src/internal/appSettings.ts` (the `remote-mcp` setting kind naming this file), `packages/perimeter/src/registry/remoteMcpApps.ts` (`planRemoteMcpAppAdd` and its refusals), `packages/cli/src/commands/provider/index.ts` (`mcp add`, `show`, `tool`, the probe's warnings), `packages/cli/src/lib/gateway/remoteMcpApps.ts` (the rows, the pin in `remote_mcp_credentials`), `packages/cli/src/commands/secret/index.ts` (the pin on `secret set`, dropped on `secret unset`), `apps/every-app-gateway/src/db/remote-mcp.schema.ts` (migration 0011)
+- https://modelcontextprotocol.io/specification (Streamable HTTP transport, tool annotations `readOnlyHint` and `destructiveHint`, authorization with `resource_metadata`)