Custom connectors

A custom connector lets the agent use a tool that isn't on Granular's list, as long as the tool offers an MCP connection address or a program you can run. Click ＋ Custom connector in Settings → Connectors and choose one of three ways to add it.

MCP (Model Context Protocol) is the common standard that lets an AI agent talk to other apps. Tools that support it publish a connection address (a web address such as https://mcp.example.com/mcp) or a small program you run on your computer. For the bigger picture, see Connectors.

Before you start

Check the tool's own documentation for one of these:

• A program to run on your computer: a command and its arguments, such as npx -y some-mcp-server. If it needs a key, note the setting name it expects, such as API_TOKEN. A command that starts with npx or node needs Node.js, free from nodejs.org.
• A remote address that uses a key or token, plus the token, and the name of the header it goes in (usually Authorization). A header is a labelled line sent along with every request; the token rides in it.
• A remote address that you sign in to in your browser, with nothing to paste.

If the tool is one of Granular's own, such as Notion or GitHub, use Built-in connectors instead. For Google and other popular apps, see Connect an app.

The three ways to add one

1. Open Settings and click Connectors.
2. Click ＋ Custom connector at the top right. The Add a custom connector drawer opens.
3. Pick one of the three choices at the top:
   • Your own server: "Define your own MCP server: a command that runs on this computer, or a remote address."
   • Remote tool: "Paste a tool's MCP address; you sign in to it in your browser."
   • Via Claude Code: "For tools that need Claude Code's own sign-in (GitHub, Slack, Google…). Works in Claude sessions."

Your own server

A program on your computer

1. Choose Your own server.
2. In Connector name, type a name, for example My tool. It becomes the card's title.
3. Click On this Mac. On Windows this reads On this PC.
4. In Command, type the program to run, for example npx.
5. In Arguments, type the rest of the command, for example -y some-mcp-server. Separate arguments with spaces. An argument can't contain a space itself.
6. If the tool needs a key, type the setting name it expects in Secret env var name, for example API_TOKEN. Letters are turned into capitals. A box called Secret (API_TOKEN) appears: paste the key there.
7. Click Add.

The connector gets only one secret setting. If the tool needs other settings, pass them in Arguments if the tool allows it.

A remote server with a token

1. Choose Your own server.
2. In Connector name, type a name.
3. Click Remote (HTTP). Choose Remote (SSE) only if the tool's documentation says its address uses SSE (an older way of sending replies).
4. Paste the tool's address into the address box (it shows https://server.example.com/mcp as an example).
5. In Auth header, keep Authorization unless the tool names a different header, such as X-API-Key.
6. Paste the token into Secret (token).
7. Click Add.

Paste the bare token, without the word "Bearer". When the header is Authorization, Granular adds Bearer in front of the token itself. With any other header name, the token is sent exactly as you pasted it.

Each remote connector sends one header. Add stays greyed out until Secret (token) has something in it, even for a server that needs no token (see the Figma example).

After you click Add, Granular says Added. The credential is encrypted and won't be shown again. The connector appears under the Custom tab.

Remote tool (browser sign-in)

Use this for a tool that gives you an MCP address and lets you sign in on its website, with nothing to paste. It doesn't need Node.js, even though the form's note mentions it.

1. Choose Remote tool.
2. Optional: in Account name, type a label.
3. Paste the tool's address into the address box (it shows https://mcp.example.com/mcp as an example).
4. Click Add & sign in. This saves it; your browser doesn't open yet.
5. Click the Custom tab, then the new card. It shows an orange ! and the status Needs sign-in: reconnect.
6. Click Reconnect. Your browser opens on the tool's website.
7. Sign in and approve access, then come back to Granular. The card shows Connected.

A browser only opens when you click Reconnect or Finish sign-in in Settings, never by itself in the middle of a task. You can't change a Remote tool's address after adding it; remove it and add it again instead.

Via Claude Code

Use this for a tool whose browser sign-in only works with apps the tool has approved, such as Claude Code. Granular registers the tool with Claude Code, and you finish the sign-in in a terminal.

1. Choose Via Claude Code.
2. In Connector name, type a short name such as github. Spaces become dashes, and other symbols are removed.
3. Paste the tool's address into the address box. It must start with https://.
4. Click Connect.
5. Granular says Registered “github”. Finish the one-time sign-in below. If you added it before, it says it's already registered instead; carry on the same way.
6. Open the session's Terminal tab, type claude and press Enter.
7. Type /mcp and press Enter, pick your tool, and choose Authorize.
8. Approve access in the browser that opens.

The tool then appears under This computer in Settings, Connectors, and works in Claude chats. Other models can reach it through the Bridge. See This computer connectors for how to manage it.

Test it

1. Click the connector's card under Custom.
2. Click Test.

Granular starts or contacts the server and checks that it answers. If it works you see, for example, Custom tool (My tool): connected (8 tools). For a remote server, Granular confirms it can reach the address with your token but doesn't count the tools, so the note just says connected.

What you'll see

• The card sits under the Custom tab. Under its name it says Granular, and its description shows the address or command.
• Its status in the drawer is one of Not tested yet, Connected or Signed in, but calls are failing. A Remote tool can also show Needs sign-in: reconnect, Sign-in didn't finish: click to complete or Browser sign-in unsupported: use a token.
• The card's corner shows a check mark when it works and an orange ! when it needs you.

Change or undo it

Click the card to open its drawer.

• Turn it off: switch off On. It stays saved, but no chat can use it.
• Limit it to some projects: next to Available in:, click All projects and tick only the projects you want.
• Rename it: next to Connector name, click Rename, type the new name and press Enter.
• Change its settings (Your own server only): click Edit settings. You can change where it runs, the command, arguments, secret setting name, address and header. Leave the secret box empty to keep the current secret, or paste a new one. Click Save.
• Remove it: click Remove, then Remove again to confirm, or Keep it. Its saved secret or sign-in is deleted from your computer.

Which models can use them

In short: in Codex chats, only an Authorization header is sent. If your server can take its token that way, use it. To choose which connectors a chat uses, see Connectors in chat.

Example: Figma's Dev Mode server

Figma's online connector only lets apps it has approved sign in, so Figma isn't a built-in connector. Figma's desktop app can instead run a small server on your own computer that needs no token.

1. In the Figma desktop app, open a design file.
2. Turn on Figma's Dev Mode MCP server in Figma's preferences. It needs a Figma seat that includes Dev Mode. Figma shows the server's address, usually http://127.0.0.1:3845/mcp.
3. In Granular, click ＋ Custom connector and choose Your own server.
4. In Connector name, type Figma.
5. Click Remote (HTTP) and paste Figma's address.
6. Clear the Auth header box completely, so no header is sent.
7. Type any placeholder, such as none, into Secret (token). It's needed to enable Add, but it's never sent.
8. Click Add, open the new Figma card and click Test.

It works in Claude, Codex and Gemini chats. Figma must stay open with a file for the connector to answer; when Figma is closed, the agent can't reach it.

Limits

• One secret per connector: one secret setting for a program on your computer, one header for a remote server.
• No spaces inside an argument.
• Your computer only. Custom connectors stay on the computer where you added them.
• A Remote tool's address can't be edited after adding. Remove it and add it again.
• Browser sign-in through Remote tool only works with tools that let any app register for sign-in. If yours refuses, use a token with Your own server, or Via Claude Code.
• Codex sends only an Authorization header, and an SSE-only server may not work there.

Troubleshooting

If Add stays greyed out
A required box is empty: Connector name, Command (for a program) or the address (for a remote server), or the secret box. A remote server always needs something in Secret (token).

If you see "Missing credential - add it and save first."
The connector has a header or secret setting but no saved secret. Click Edit settings, paste it and click Save.

If you see "The server did not respond in time."
The program started but didn't answer within about 12 seconds. Check the command and arguments against the tool's instructions. Some programs need extra arguments before they act as an MCP server.

If you see "The server stopped before it finished starting up: …"
The program couldn't start. Read the text after the colon. "command not found" usually means the program, or Node.js, isn't installed. A missing setting means it needs a key: add it with Secret env var name.

If you see "Server returned 401." or "Server returned 403."
The server refused your token. Check the token and the Auth header name. Make sure you pasted the token without the word "Bearer".

If it passes Test but the agent can't use it in a chat
A program on your computer gets only basic settings plus its one secret during a chat. If it relies on another setting from your own terminal, pass that in Arguments if the tool allows it.

If it works in Claude chats but not in Codex chats
Your server probably uses a header other than Authorization, which Codex doesn't send, or it only supports SSE. If the server accepts an Authorization header, switch to that. Otherwise use the connector in Claude or Gemini chats.

If you see "Needs sign-in: reconnect" or "Sign-in didn't finish: click to complete" (Remote tool) Click Reconnect or Finish sign-in and approve access in your browser.

If you see "Sign-in started but didn't finish. Complete the sign-in in the browser (approve access), then click Reconnect again."
The browser page was closed before you approved. Click Reconnect and finish in the browser.

If you see "Browser sign-in unsupported: use a token" (Remote tool) That tool doesn't allow browser sign-in from Granular. Remove it, then add it with Your own server and a token, or try Via Claude Code. The message mentions GitHub, but it applies to any tool.

If you see "Pick a short name - letters, numbers, dashes (e.g. github)." (Via Claude Code) Use a name that starts with a letter or number, up to 31 characters.

If you see "The address must start with https://." (Via Claude Code) Paste the full address, starting with https://.

If you see "Claude Code isn't available on this computer." (Via Claude Code) Via Claude Code needs Claude Code installed. Use Remote tool or Your own server instead.

Related