Skip to main content
Custom MCP servers let you attach remote MCP tools to ref-thread agents. Connect a server once, then choose which connected servers and integrations are available to each thread.

​
Connect a custom MCP server

  1. Go to Settings in Ref Plans
  2. Click the Integrations or Connectors tab
  3. Add a custom MCP server with a name and URL
  4. Choose an authentication method:
    • None — Use for public or unauthenticated servers
    • Custom headers — Add static headers, such as an API key or bearer token
    • OAuth — Use the authorization-code flow with dynamic client registration; no manual client ID or client secret setup is required
  5. Click Verify or Save to connect to the server
  6. Review the tools Ref found on the server, then save the connection
Ref verifies the server before saving it. If the server is unreachable or returns an invalid MCP response, Ref rejects the connection and shows an inline error.

​
Usage

After you connect a custom MCP server, choose when to attach it to a ref-thread:
  1. Open a plan and start or select a ref-thread
  2. In the message composer, click the + connectors button
  3. Use the checkbox rows grouped under MCP Servers and Integrations to choose which connected tools attach to that thread’s runs
  4. Send your message
Connector selection is per-thread. Changing the checkboxes overrides your Settings defaults for that thread only; other threads and your defaults are unaffected. Use Configure Integrations in the connectors menu to jump back to Settings when you need to add, remove, or update a connection.

​
Support

FeatureSupportNotes
Transport: Streamable HTTP✅ SupportedThe only transport supported for custom servers.
Transport: stdio / legacy HTTP+SSE❌ Not supportedOnly remote HTTP(S) servers can be added.
Capability: Tools✅ SupportedThe only capability currently exercised.
Capability: Resources❌ Not supportedNot surfaced to the agent.
Capability: Prompts❌ Not supportedNot surfaced to the agent.
Auth: None✅ Supported
Auth: Custom headers (API key / bearer token)✅ Supported
Auth: OAuth 2.0 with dynamic client registration✅ SupportedTokens refresh automatically.
Attach scope: ref-thread agents✅ Supported
Attach scope: other harnesses (Cursor, Devin, Warp OZ)❌ Not supportedThose harnesses manage their own MCP configs today.
Sharing scope: team-shared servers❌ Not supportedConfigs are user-scoped only, like Linear/Asana.

​
Get help

If you have any issues, please reach out to help@ref.tools. We’re happy to help you get started!