# Use Things I FW in your AI apps and editors

Connect once in each app, then ask it to use your saved references. This guide is for people connecting their own library; the app owner’s Supabase/Vercel deployment instructions are in [MCP_SETUP.md](MCP_SETUP.md).

Website version: [Things I FW setup guide](https://thingsifw.vercel.app/mcp-setup.html).

Client instructions checked against official documentation on **28 October 2026**. Menu names and availability can vary by version, plan and organization policy. These are documented configuration paths, not a claim that every client/version has been tested against the live service.

## Before you start

You need a Things I FW account with some saved images, and an AI app that supports **remote Streamable HTTP MCP with OAuth**. MCP is how the AI app calls Things I FW’s tools. OAuth is the browser sign-in where you choose which parts of your library it can read.

Use these connection details in every client:

| Setting | Value |
| --- | --- |
| Name / server ID | `things-i-fw` |
| Server URL | `https://thingsifw.vercel.app/api/mcp` |
| Transport | HTTP / Streamable HTTP |
| Authentication | OAuth, with automatic/dynamic client registration |

Sign in with the account that holds your saves. On the Things I FW consent screen, choose **My whole library** or **Only the sections I choose**, then **Allow read access**. Each person connects their own account. The connector reads your own saved images; other people’s shared boards are excluded. It cannot add, edit or delete saves.

You do not need a Supabase, Gemini or OpenAI API key to connect this library. Your AI app may have its own subscription or model billing. Leave custom authorization headers and static client credentials empty for automatic registration. Never paste the app owner’s server secrets into an editor, chat or configuration file.

If a configuration file already exists, merge the new server into its existing `servers` or `mcpServers` object. Keep your other servers and settings. `~` means your home folder; on Windows, open the corresponding folder under your user profile.

## Choose your app

- [ChatGPT](#chatgpt)
- [Claude web, Desktop and Cowork](#claude-web-desktop-and-cowork)
- [VS Code with GitHub Copilot](#vs-code-with-github-copilot)
- [Cursor](#cursor)
- [Claude Code](#claude-code)
- [Codex app, CLI and IDE extension](#codex-app-cli-and-ide-extension)
- [Gemini CLI](#gemini-cli)
- [First test and example prompts](#first-test-and-example-prompts)
- [Troubleshooting](#troubleshooting)

## ChatGPT

1. On ChatGPT web, open **Plugins → + → Add custom MCP server**. Some accounts expose this under Apps/developer settings.
2. Name it **Things I FW** and enter `https://thingsifw.vercel.app/api/mcp`.
3. Choose **OAuth** and automatic/dynamic registration. Leave static client credentials empty.
4. Create and install the plugin. Complete browser sign-in and **Allow read access** in Things I FW.
5. Start a new chat, type **@**, and select **things-i-fw** before sending the [first test](#first-test-and-example-prompts).

To check imported tools, open the plugin’s app entry (under **Apps 1** in some interfaces) and **View details**. You should see four read tools. If an older chat says no tools are available, select **Manage → Refresh tools**, then start a new chat and select the plugin again. Successful sign-in alone does not prove a tool was called.

Sources: [OpenAI custom MCP setup](https://developers.openai.com/api/docs/guides/custom-mcp-server), [refreshing and testing tools](https://developers.openai.com/plugins/deploy/connect-chatgpt#refresh-metadata).

## Claude web, Desktop and Cowork

1. Open **Customize → Connectors → Add → Add custom connector**. On team accounts, an owner may need to add it under Organization settings first.
2. Enter **Things I FW** and `https://thingsifw.vercel.app/api/mcp`.
3. Keep OAuth sign-in enabled. If offered an OAuth client choice, select **Register automatically**. Leave fixed request headers empty.
4. Click **Connect**, sign in to Things I FW and approve your library or selected sections.
5. In a new conversation, open **+ → Connectors** and enable Things I FW. Send the first test.

Use the remote connector flow for Claude Desktop/Cowork as well. This hosted HTTP server does not need a local `claude_desktop_config.json` process or an `npx` bridge. Configure Claude Code separately using its section below.

Source: [Claude remote connector setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## VS Code with GitHub Copilot

1. Update VS Code, sign in to GitHub Copilot and open your project. Use a tool-capable agent session.
2. Open the Command Palette: **Cmd+Shift+P** on macOS or **Ctrl+Shift+P** on Windows/Linux. Run **MCP: Add Server**.
3. Choose **HTTP**, enter `https://thingsifw.vercel.app/api/mcp`, and use server ID **things-i-fw**.
4. For personal use, choose **Global → Copilot Global** when available. Start the server and finish browser sign-in and library consent when prompted.
5. Enable its tools in **Chat: Open Customizations → Tools**. Older/Local sessions use **Configure Tools** in the chat input. Send the first test and inspect the tool result.

For manual configuration, current Copilot Global uses `~/.copilot/mcp-config.json` (or your configured `COPILOT_HOME`):

```json
{
  "mcpServers": {
    "things-i-fw": {
      "type": "http",
      "url": "https://thingsifw.vercel.app/api/mcp"
    }
  }
}
```

For VS Code’s **Local** harness, the workspace alternative is `.vscode/mcp.json` with a different outer key:

```json
{
  "servers": {
    "things-i-fw": {
      "type": "http",
      "url": "https://thingsifw.vercel.app/api/mcp"
    }
  }
}
```

The configuration must belong to the harness running your chat. A file’s presence alone does not enable tools in every harness.

**Copilot cloud agent and Copilot code review:** GitHub currently documents that these do not support remote MCP OAuth. This connector requires OAuth, so use a compatible interactive client rather than putting Supabase server secrets into GitHub settings.

Sources: [VS Code setup](https://code.visualstudio.com/docs/agent-customization/mcp-servers), [configuration formats](https://code.visualstudio.com/docs/agents/reference/mcp-configuration), [Copilot cloud limitations](https://docs.github.com/en/copilot/concepts/customizations/mcp).

## Cursor

1. Open Cursor’s **Customize / MCP** settings (called **Tools & MCP** in some versions), or edit `~/.cursor/mcp.json` for personal use. `.cursor/mcp.json` scopes it to one project.
2. Add this entry, keeping existing servers:

```json
{
  "mcpServers": {
    "things-i-fw": {
      "url": "https://thingsifw.vercel.app/api/mcp"
    }
  }
}
```

3. Enable the server, then choose **Connect / Authenticate** if prompted. Complete Things I FW sign-in and library consent in your browser.
4. Open an Agent conversation with the server enabled and send the first test. Review any tool approval prompt.

Source: [Cursor MCP configuration and OAuth](https://cursor.com/docs/mcp).

## Claude Code

With Claude Code installed, run this in a terminal. User scope makes the connection available across your projects:

```sh
claude mcp add --transport http --scope user things-i-fw https://thingsifw.vercel.app/api/mcp
```

Start Claude Code, run `/mcp`, select **things-i-fw**, and choose its authentication option. Complete browser sign-in and library consent. Return to Claude Code, check that the server is connected, and send the first test. `claude mcp list` shows configured servers; configuration alone does not prove authentication succeeded.

For a project-shared configuration, use `--scope project` instead of `--scope user`. Teammates still authenticate separately. If the server name already exists, inspect it with `claude mcp get things-i-fw` rather than repeatedly adding duplicates.

Source: [Claude Code MCP setup and authentication](https://code.claude.com/docs/en/mcp).

## Codex app, CLI and IDE extension

For clients using the local Codex host, you can add the server through its MCP settings and select **Streamable HTTP**, then **Authenticate**. The terminal route is:

```sh
codex mcp add things-i-fw --url https://thingsifw.vercel.app/api/mcp
codex mcp login things-i-fw
```

Complete browser sign-in and library consent. If adding the server already completed OAuth, a second login is unnecessary. Start a fresh session and use `/mcp` where available to check the server and tools, then send the first test.

Manual alternative in `~/.codex/config.toml`:

```toml
[mcp_servers.things-i-fw]
url = "https://thingsifw.vercel.app/api/mcp"
```

Then run `codex mcp login things-i-fw`. Local Codex clients on the same host share this configuration. ChatGPT web needs its own plugin setup; it does not read this local file.

Source: [Official OpenAI MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## Gemini CLI

With Gemini CLI installed, merge this into your user configuration at `~/.gemini/settings.json` (or `.gemini/settings.json` for one project):

```json
{
  "mcpServers": {
    "things-i-fw": {
      "httpUrl": "https://thingsifw.vercel.app/api/mcp"
    }
  }
}
```

Use **`httpUrl`** for this Streamable HTTP server; Gemini CLI’s `url` field selects SSE.

Restart Gemini CLI. Inside its interactive session, run `/mcp auth things-i-fw`, finish browser sign-in and library consent, and use `/mcp` to check the tools. Send the first test. Perform OAuth on a machine with a browser and a working local callback; headless/SSH/container environments can require a different client setup.

This config is for **Gemini CLI**, not the Gemini consumer chat website. Using Gemini to index images in Things I FW is a separate feature; it does not connect an AI client automatically.

Source: [Gemini CLI MCP transport and OAuth setup](https://geminicli.com/docs/tools/mcp-server/).

## First test and example prompts

Start with this in the connected client:

> Use Things I FW’s list_sections tool with offset 0 to list my accessible sections. Do not search the web.

Expand the tool activity and confirm an actual `list_sections` call returned your section names. Tool names may have a client-added prefix. A successful empty `sections` array means the account/grant has no visible sections; it is different from tools being unavailable.

The four read tools are:

| Tool | Purpose |
| --- | --- |
| `list_sections` | List sections visible to this connection. |
| `get_section` | Retrieve saved image references from one section. |
| `search_references` | Search saved titles/descriptions; visual concepts when indexing is enabled. |
| `get_images` | Fetch actual image pixels for up to four saved image IDs per call. |

Then try:

> Use Things I FW to fetch my Packaging section. Call get_images to inspect the actual images, then suggest three directions for a coffee brand using only those references.

> Find eight orange, typography-heavy packaging references in my Things I FW saves. Fetch the images in batches of four and explain the useful details. Do not use web search.

Rendering and visual inspection depend on the AI client and model. The connector returns JPEG image blocks; it does not guarantee every editor will show an inline gallery. Deleted or blocked original images may be unavailable.

## Optional: search by look and feel

Section and keyword lookup work without visual indexing. For concepts such as “grainy orange posters,” open [Things I FW connection settings](https://thingsifw.vercel.app/connect.html), enable **visual search**, and choose **Index saved images**. This permits compressed images to be sent to Google Gemini for searchable descriptions. The app owner must have configured the indexing service. Large libraries can take time because daily limits apply.

## Troubleshooting

- **Signed in, but no tools in chat:** confirm the server’s four tools are listed, enable them in the current conversation/harness, then refresh/restart and open a new session. In ChatGPT, use **Manage → Refresh tools** on the underlying app connection.
- **401 / expired connection:** reconnect through the client’s OAuth flow. Signing into the website alone does not refresh the client’s credentials.
- **403 / access revoked:** open Things I FW connection settings and check the approved account and sections. Reconnect if access was revoked.
- **Empty or missing sections:** check which account you connected and whether you selected only some sections. Shared boards from other people are excluded.
- **Visual search misses images:** confirm opt-in and indexing progress. Try section names or words already in saved titles first.
- **429:** pause for a minute and retry; the connector limits request frequency.
- **503 / registration or signing-key errors:** send the exact error to the app owner. Deployment/OAuth configuration belongs in [MCP_SETUP.md](MCP_SETUP.md); users should not need to edit Supabase.
- **No custom MCP option:** check client updates, account eligibility and organization policy. MCP support without interactive OAuth is insufficient for this connector.

To disconnect, open **Things I FW → Settings → Connect AI apps → Connected apps → Revoke access**, then remove/disconnect the server in the AI client. Revocation stops future reads; it does not remove references already retrieved into past conversations.