Fix a failing MCP connection

Every section below starts with the literal message you'll see, whether it's in the terminal, in the chat or on the browser screen. Vitrina's own screens are Spanish, so their messages are quoted as they appear.

"I could not connect to the server"

Almost always it is the address. Vitrina answers MCP at the root of the host:

https://api.vitrinadev.com/mcp

Not under /api/v1. That is a 404, and the client translates it into "server unavailable":

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.vitrinadev.com/api/v1/mcp

404

To check that you typed the address right, ask for it with the browser or with curl. With no credential and a GET, Vitrina identifies itself:

curl https://api.vitrinadev.com/mcp

{
  "name": "vitrina",
  "version": "1.0.0",
  "transport": "streamable-http",
  "auth": "bearer-api-key"
}

If that answers, the address is fine and the problem is elsewhere.

"Your AI is not authorised": the 401

There are two different 401s and they say different things.

With no credential. That's normal, and it's how the OAuth flow starts. Vitrina answers with the address of its authorization server in a header, and that's where the client finds out where to go next:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing bearer token",
    "requestId": "1e186199-a51c-4987-8e33-ba8971c51fa5"
  }
}

With a credential that no longer works. This one is a problem:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "requestId": "0aac9b83-e5e0-4f4c-88cb-b0e2b8fbe3a0"
  }
}

That is the exact message of a revoked connection, and it shows up on the call right after the revocation: there is no grace period. The causes, in order of frequency:

1. Somebody disconnected the connection. Look at «Aplicaciones conectadas» and «Conexiones activas» under Connections → MCP. If your connection is in neither, it was revoked and you have to authorise again from the client.
2. You pasted an incomplete key. A connection key is sk_ plus 43 characters. A line break or one extra space when copying turns it into something else.
3. The token expired and couldn't be renewed. An OAuth token lasts an hour and the client renews it by itself. If the connection was disconnected in the meantime, the renewal fails too:

{
  "error": "invalid_grant",
  "error_description": "refresh token invalid, expired, or reused"
}

"I cannot find that tool" / the model says it cannot do it

{
  "content": [
    { "type": "text", "text": "MCP error -32602: Tool tenant_settings_update not found" }
  ],
  "isError": true
}

This is not an installation error: it is the connector profile working. A connector sees a curated, read-only subset; everything that writes, sends messages or touches the settings does not exist for it. The full list of what it can do is in Connector tools.

If what's missing is costs, margins or commissions, that's something else: the economic-data checkbox. It arrives switched off, and without it those six tools are never registered. To add them, authorise again with it ticked, or create a new connection key with the box on. It can't be switched on over a connection that already exists.

"Not Acceptable" when testing with curl

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Not Acceptable: Client must accept both application/json and text/event-stream"
  },
  "id": null
}

The transport is Streamable HTTP: a call has to declare that it accepts both types. An MCP client does it on its own; when testing by hand, you have to put it in:

curl -X POST https://api.vitrinadev.com/mcp \
  -H "Authorization: Bearer $VITRINA_CONNECTOR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response arrives as an event, not as bare JSON: one event: message line and one data: {…} line.

«Aplicación desconocida» on the authorisation screen

Aplicación desconocida
unknown client_id

That is Vitrina saying unknown application. The client turned up with an identity this server does not recognise. It happens when the registration the client had stored went stale: it was made against another server, or against an earlier version of this one.

In Claude Code you fix it by deleting what is stored for that server and authorising again:

claude mcp logout vitrina
claude mcp login vitrina

In Cursor, a fresh cursor-agent mcp login vitrina registers itself again.

«redirect_uri inválido»

redirect_uri inválido
This redirect URI is not registered for the application.

The client asked for the authorisation to be returned to an address it has not declared. It is almost never something you typed: there are two cases.

• A local client listening on a port it picked on the fly. That's normal. Vitrina compares a localhost client's redirect_uri ignoring the port (RFC 8252 §7.3).
• A misconfigured client, pointing at a server different from the one it registered with.

If it shows up with a freshly installed Claude Code or Cursor, logout and login again.

It asks you to sign in over and over

The window your AI client opens uses your browser, so it needs a live Vitrina session and cookies enabled. Open Vitrina in that same browser, sign in, and try again.

In a private window, or with third-party cookies blocked, the cycle repeats until you allow them.

The authorisation code "no longer works"

{
  "error": "invalid_grant",
  "error_description": "code not found, expired, or already used"
}

An authorisation code is redeemed once and lives two minutes. If your client retried the exchange, or if you went back in the browser and repeated the redirect, the second attempt fails like this. Retrying does not fix it: the flow has to start again.

You connected the wrong workspace

The connection is created in the workspace you had active when you authorised, and it cannot be moved. Disconnect it under «Aplicaciones conectadas», switch workspace in the application, and authorise again from the client.

"Add custom connector" is missing, or the connector is not in the chat

The button is at the end of the list under Customize → Connectors in your account (claude.ai/customize/connectors), not in the chat's settings. If you looked under Settings on claude.ai, that is a different screen. In Claude Desktop, though, it is under Settings… → Connectors; if it is not there, update the application.

If you already added it and it does not appear while chatting, it is the other step: a connector is switched on per conversation, in the chat's connector picker.

You disconnected an application by mistake

There is no undo: the permissions are revoked immediately and the renewal chain is burnt. Add the connector again in your client and authorise it again. The costs-and-margins checkbox is unticked again, so tick it again if you needed it.

None of the above

Every API error carries a requestId. Send it to us exactly as it is: it is what lets us find that precise call in the logs.