Refsee MCP

Your visual library.
Where you think.

Search references, compare frames and build moodboards directly in ChatGPT, Claude and your favourite AI tools.

Choose your client

Sunlit tennis court with a wide composition

A backlit outdoor portrait framed by leaves

A close-up of a tennis player in warm light

Real references from the library. Follow a frame to its source.

One URL. Your own account.

Remote MCP over Streamable HTTP, with OAuth sign-in on Refsee.

https://mcp.refsee.com/mcp

A direct connection
to your creative workflow.

MCP stands for Model Context Protocol. It lets your AI assistant use Refsee’s real search and your account’s tools. Describe what you need in the conversation, then explore actual frames instead of a list of invented references.

01Find the direction
Describe a scene, a colour palette, a lighting style or a feeling. Refine with cinema, format and framing filters.
02Look closer
Compare the frames, follow source links and explore visually similar references. A compatible chat can display an interactive gallery.
03Keep what works
Select the useful frames, save them to a private moodboard and keep developing the idea in Refsee.

Start with your client.

You need a Refsee account and a client that supports remote MCP with OAuth. The service runs on Refsee; there is no local server to maintain.

Web app

Connect ChatGPT

Bring reference search and interactive moodboards into your conversation.

1.Open ChatGPT settings, then Security and login. Enable Developer mode if it is available for your account or workspace.
2.Open Plugins, choose the Personal tab and select Create app / New plugin. Some versions of ChatGPT call this section Apps.
3.Name it Refsee, paste the server URL below and choose OAuth. The server supports automatic client registration; leave optional client credentials empty.
4.Connect, sign in on Refsee and approve the permissions for your account.
5.Start a new conversation, select Refsee from the plugin menu and ask for a visual direction. Ask to show a gallery when you want to compare frames.

MCP server URL

https://mcp.refsee.com/mcp

Developer mode availability depends on your ChatGPT plan and workspace settings. Interactive galleries require a client with MCP Apps support.

Official ChatGPT instructions

Web & Desktop

Connect Claude

Connect your library once, then research and collect references with Claude.

1.Open Claude settings and go to Connectors.
2.Choose Add custom connector. Enter Refsee as the name and paste the server URL below.
3.Choose Connect. Sign in on Refsee, review the requested permissions and authorize the connection.
4.Enable Refsee in your conversation and ask Claude to search for references or open a moodboard.

Remote connector URL

https://mcp.refsee.com/mcp

Use the remote connector settings in Claude Desktop too. Custom-connector access depends on your plan and organization settings; a directory listing is not required for manual setup.

Official Claude instructions

Terminal

Connect Claude Code

Keep visual research close to the project you are building.

1.Run the command below in a terminal where Claude Code is installed.
2.Open Claude Code and run /mcp. Select Refsee and complete the browser sign-in.
3.Ask Claude Code to use Refsee. The user scope makes the connection available across your projects.

Terminal command

claude mcp add --transport http --scope user refsee https://mcp.refsee.com/mcp

Inside Claude Code

/mcp

The MCP service runs on Refsee. You do not need to install Python or run a local Refsee server.

Official Claude Code instructions

Editor

Connect Cursor

Give your coding agent access to real visual references and your moodboards.

1.Open Cursor Settings → Tools & MCP, or edit your user configuration at ~/.cursor/mcp.json.
2.Add the Refsee entry shown below to mcpServers, keeping any existing server entries.
3.Enable Refsee and complete its OAuth sign-in when Cursor prompts you.
4.Use Agent chat and ask it to find references with Refsee.

~/.cursor/mcp.json

{
  "mcpServers": {
    "refsee": {
      "url": "https://mcp.refsee.com/mcp"
    }
  }
}

For a project-specific connection, use .cursor/mcp.json in that project. The configuration contains only the public server URL.

Official Cursor instructions

Editor / Copilot

Connect VS Code

Use Refsee through VS Code’s built-in remote MCP support.

1.Open the Command Palette and run MCP: Add Server. Choose HTTP and enter the Refsee server URL.
2.Alternatively, add the configuration below to .vscode/mcp.json in your workspace.
3.Start the Refsee server entry and complete the browser authorization.
4.Enable its tools in a compatible agent chat, such as Copilot Agent mode.

.vscode/mcp.json

{
  "servers": {
    "refsee": {
      "type": "http",
      "url": "https://mcp.refsee.com/mcp"
    }
  }
}

Use MCP: List Servers to check the connection. Your organization may control which MCP servers are available.

Official VS Code instructions

App & terminal

Connect Codex

Search for a visual direction from your Codex workspace.

1.Run the terminal commands below with Codex installed. The second command opens the Refsee OAuth sign-in.
2.The same remote server can also be configured in ~/.codex/config.toml.
3.Check the connected server with codex mcp list, then ask Codex to use Refsee.

Terminal commands

codex mcp add refsee --url https://mcp.refsee.com/mcp
codex mcp login refsee
codex mcp list

Alternative: ~/.codex/config.toml

[mcp_servers.refsee]
url = "https://mcp.refsee.com/mcp"

Configure the server once. Use either the add command or the TOML entry, then complete OAuth.

Official Codex instructions

Terminal

Connect Gemini CLI

Connect the remote Refsee service to Gemini CLI.

1.Add Refsee to mcpServers in ~/.gemini/settings.json using the httpUrl field for Streamable HTTP.
2.Restart Gemini CLI and run /mcp to inspect available servers.
3.Run /mcp auth refsee if authentication is requested, then sign in through Refsee in your browser.

~/.gemini/settings.json

{
  "mcpServers": {
    "refsee": {
      "httpUrl": "https://mcp.refsee.com/mcp"
    }
  }
}

Inside Gemini CLI

/mcp auth refsee

These instructions are for Gemini CLI. Google has moved personal/unpaid users to Antigravity CLI; follow the client currently supported by your account. Merge the Refsee entry into existing settings.

Official Gemini CLI instructions

App & terminal

Connect OpenCode

Add Refsee as a remote MCP server in OpenCode.

1.Add the remote Refsee entry to opencode.json in your project or ~/.config/opencode/opencode.json for your user.
2.Run opencode mcp auth refsee and complete the browser sign-in.
3.Restart OpenCode and ask it to use Refsee for visual-reference research.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "refsee": {
      "type": "remote",
      "url": "https://mcp.refsee.com/mcp",
      "enabled": true
    }
  }
}

Terminal command

opencode mcp auth refsee

OpenCode manages the OAuth token for you. No Refsee password, session cookie or AI API key belongs in this configuration.

Official OpenCode instructions

Your client is not listed? Use the same URL with Streamable HTTP + OAuth.

Create a Refsee account

Give it a real brief.

Copy a starting point, then make the subject, mood and deliverable your own.

01Research a campaign

Use Refsee to find eight references for an electric-car film: a rainy city, cool blue light, reflections and wide shots. Show a gallery and explain what each frame contributes.

02Explore a visual language

Find portrait-format cinema references with warm side lighting. Show a varied shortlist, then explore references visually similar to the third frame.

03Keep the direction

Create a private Refsee moodboard called Night Drive, add my selected frames and write a short description of the visual direction. Return the moodboard link.

Connected to you.

Sign-in happens on Refsee. Each connection belongs to your account, with its own permissions and an independent revoke control. There are no session cookies or AI API keys to copy into a configuration.

Manage your AI connections

Your plan still applies

Search access, related references and viewing limits follow your Refsee plan. Opening video details uses your video-view allowance.

Your boards stay yours

New moodboards are private. Editing a board or saving frames to it requires ownership; another user’s private board is unavailable.

Control the connection

Review the permissions during sign-in. Revoke access at any time from AI connections. A connection expires after 90 days and then needs to be connected again.

Read the integrations privacy notice

The tools behind the conversation.

16 focused tools. Useful as structured results in any supported client, with galleries where MCP Apps are available.

Search & discover

Visual descriptions, cinema, title, voiceover and motion search; format, framing, sorting and pagination.

search_referencessearchsuggest_searchesget_related_references

Inspect the reference

Frame details, source links, video metadata and citation-ready results. Video details use your viewing allowance.

get_frameget_videofetch

Build your moodboard

Read your boards, create private collections, edit descriptions and save selected frames. Editing requires ownership.

list_moodboardsget_moodboardcreate_moodboardupdate_moodboardadd_to_moodboard

Account & context

Your connected account, plan and remaining credits, plus recent queries and viewed references.

get_accountget_search_history

Show the gallery

Interactive reference and moodboard views in MCP Apps clients. Other clients receive the same structured data and links.

show_referencesshow_moodboard

A few useful answers.

Do I need an OpenAI or Anthropic API key?

Not to connect Refsee. Sign in to your AI client normally, then authorize your Refsee account through OAuth. The public MCP URL contains no secret.

Why do I see links instead of an interactive gallery?

The gallery uses MCP Apps. Clients without that UI support still receive the reference IDs, metadata and source links. In a supported chat, ask the assistant to show the references in a gallery.

What if I cannot find the connector settings?

Check that your client is up to date and that remote MCP is enabled for your account or workspace. Menu names vary by version. Use the official client instructions linked in the setup section.

Why am I asked to reconnect?

A connection may have been revoked or reached its 90-day lifetime. Connect Refsee again through the client’s settings. Each client connection can be managed independently.

What should I do after a save times out?

A write may have completed even when its response was lost. Check your moodboards before creating a second board. The gallery keeps unconfirmed frames selected; adding the same frame to a board again does not create a duplicate.

Can it generate images or edit my video?

This MCP integration is for reference research and moodboards. It does not expose Refsee’s image-generation, video-generation, billing or account-administration tools.

Need a hand connecting? hello@refsee.com

Your visual library.Where you think.