Troubleshooting the Functionize MCP Connection

Most Functionize MCP connection problems come down to one of five things: an absolute path that is not absolute, a configuration file that is not valid JSON, an app that was closed rather than quit, a stale token, or a sign-in method that does not match how your organisation actually signs you in. This article covers each one.

If you have not connected yet, start with Connect Claude Code or Connect Claude Desktop instead.

Five common symptoms, their usual cause, and the fix for each

Let Claude diagnose it for you

Before working through this by hand, try pasting this prompt into Claude Code. It checks the common causes in order and tells you what it found.

My Functionize MCP connection is not working. Diagnose it. Work out my operating
system yourself and use the right paths.

1. Check the server is reachable. Expect HTTP 200 from:
   https://mcp.functionize.com/.well-known/oauth-protected-resource

2. Check node --version is 18 or newer.

3. Show me my current MCP configuration:
     Claude Code:    run "claude mcp list"
     Claude Desktop: read the config file
       macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
       Windows: %APPDATA%\Claude\claude_desktop_config.json

4. For any Functionize entry you find, check all of the following and tell me which
   fail:
   - Does the URL point at mcp.functionize.com, and NOT internal-dev.functionize.com?
   - Is "command" an ABSOLUTE path that exists and is executable, rather than a
     bare "npx"?
   - Is the whole config file valid JSON?

5. Tell me exactly what is wrong and what to change. Do not change anything yet -
   show me first.

The server is not listed after restarting

Almost always the command path in your Claude Desktop configuration is not actually executable.

A bare "npx" will not work. Claude Desktop launches commands without your shell, so anything provided by nvm, fnm or Volta is invisible to it. You need the full path — and on Windows, the .cmd file.

Find the real path:

macOS

which npx

Windows (PowerShell)

(Get-Command npx).Source

Then confirm the path you put in the config actually runs:

"/opt/homebrew/bin/npx" --version

The other common cause is invalid JSON — usually a missing or extra comma after adding the new entry. Paste the file into any JSON validator before restarting.

Nothing happens when you restart Claude Desktop

The app was probably not fully quit. Closing the window leaves it running, and it will not re-read its configuration.

macOS: press Cmd+Q.
Windows: right-click the Claude icon in the system tray near the clock and choose Quit. If it is not in the tray, end the process in Task Manager.

Then reopen the app.

No browser tab opens for sign-in

Run the bridge by hand so you can watch the handshake and see any error:

/opt/homebrew/bin/npx -y mcp-remote https://mcp.functionize.com/mcp

Use your own npx path. On Windows, run the equivalent with your npx.cmd path.

You reach the sign-in page but cannot get past it

This is the most common problem in larger organisations, and it is rarely a broken connection.

Use the same credentials you use for Functionize Studio. The MCP server has no separate account and no separate password. It authenticates against your existing Functionize login, and that is also what determines which projects and teams the connection can reach.

If your organisation uses SSO, choose the SSO option on that screen rather than typing a password. If you have only ever reached Functionize through SSO, you may not have a local password at all. Do not guess at one — repeated failed attempts can lock the account. Contact your Functionize representative and we will sort out the right route for you.

Check the domain. The sign-in page is hosted at functionize.us.auth0.com, and the server behind it is mcp.functionize.com. Both are ours. If you are ever asked for Functionize credentials on any other domain, do not enter them — send it to us instead.

Nobody at Functionize will ever ask you for that password. You only ever type it into that sign-in screen.

You want to sign in again, or clear a stale token

The bridge caches tokens on disk, separately from your configuration file.

macOS

rm -rf ~/.mcp-auth

Windows (PowerShell)

Remove-Item -Recurse -Force "$env:USERPROFILE\.mcp-auth"

Then restart Claude Desktop. This clears cached tokens for every server bridged through mcp-remote, so you will be asked to sign in to those again too.

In Claude Code, run /mcp, select functionize-hosted, and re-authenticate.

You connected to an older internal build

An entry pointing at internal-dev.functionize.com will not work from outside our network. Remove it and add the production server at mcp.functionize.com.

In Claude Code:

claude mcp list
claude mcp remove <name>

In Claude Desktop, delete that entry from the configuration file. Leave any stdio "functionize" entry alone — that is a different, still-valid connection.

Clear the cached tokens as above, then quit and reopen the app.

Tools load but every call returns nothing, or says unauthorized

This should not happen. Please raise it with us, including your account email and roughly when you signed in.

You are seeing a team you did not expect

By default the connection acts as your active team — whichever one your web login lands on. If you belong to several, ask your client to list your Functionize teams: the list_agent_teams tool returns them by name, flags the default, and tells you which team the connection is currently acting as.

To pin a specific team, add the X-Functionize-Team-Id header as shown in the connection guides. Interactive clients read their configuration when the connection starts, so restart the connection after changing it.

Adding the server through the claude.ai custom connector UI hangs

If it sticks on "Checking connection…", use the configuration method in the connection guides instead. That is the path we have verified end to end.

Still stuck

Raise a ticket and include: which client and operating system you are using, the exact entry from your configuration with any team ID redacted, what node --version reports, and the point in the process where it stops. Never include your password.

Search