Skip to main content
Start by asking the client: “Read my Melso company without changing anything.” A successful company read shows that the connection, the OAuth grant and the company binding work. A client that shows “Connected” has not necessarily called a tool: check for a real result.

​
The client cannot add a custom server

Some clients limit custom MCP servers by plan, role or workspace policy. On Claude Team and Enterprise plans an Owner adds the connector for the organization. In ChatGPT, account and workspace policies decide whether Add custom MCP server appears. In VS Code, an organization policy can turn MCP servers off. Ask the administrator of that account or workspace; Melso cannot change it.

​
Sign-in fails or tools return 401

A 401 means the client has no valid OAuth access token for https://mcp.melso.ai/mcp: it is missing, expired, or was issued for something else.
  • Start the client’s sign-in again: Connect in Claude, /mcp in Claude Code, codex mcp login melso, /mcp auth melso in Gemini CLI, the Melso entry in Cursor’s MCP settings, or MCP: List Servers in VS Code.
  • Remove any Authorization header or token you added to the configuration. Melso signs in through OAuth only, and a rejected header stops some clients from trying OAuth.
  • Check that the browser reached Melso’s consent screen and that you approved the request there.

​
Requests return 403

A 403 means the token is valid but the account cannot do this. Your membership in the company may have ended, or your role or the plan may no longer allow the tool. Reconnecting does not add permissions your Melso account lacks. Check Configuración in the Melso app, or ask the company’s owner.

​
Tools are missing

A shorter list is not a failure. The server lists what the company’s plan, your role and the setup allow:
  • Without a plan that includes the tools, only read actions are listed.
  • While an autónomo’s setup is pending, only company, fiscal_profile and support_tickets_create are listed. Finish the fiscal profile, then reconnect or refresh the tool list.
  • fiscal_profile is listed for the owner or an admin.
See Permissions and approvals.

​
The assistant works in the wrong company

Each connection is bound to the company chosen at consent, and a tool argument cannot switch it. Disconnect it in Melso (Configuración, tab MCP, Desconectar), then connect again and choose the right company. To work with two companies, add one connection for each.

​
The client cannot connect

  • Use the exact URL https://mcp.melso.ai/mcp, over HTTPS, with the /mcp path.
  • Use the client’s Streamable HTTP option: --transport http in Claude Code and Gemini CLI, "type": "http" in VS Code, httpUrl in Gemini CLI’s settings.json. An SSE-only setting does not work.
  • https://docs.melso.ai/mcp is the documentation search server. It cannot read your records.
Links that start with cursor:// or vscode: need that application installed and registered to open them. Some browsers and email clients block them. Use the manual configuration on the client’s page; it is equivalent. A Claude link that opens an empty dialog lost its query string: copy the full link from Connect Claude.

​
The tools changed

When Melso adds or changes tools, some clients keep the old list. Refresh it: Refresh on the connection in ChatGPT Plugins, MCP: Reset Cached Tools in VS Code, reconnect from /mcp in Claude Code, or restart the client.

​
Revoke access

Open Configuración in the Melso app, then the MCP tab. Desconectar stops a connection at once, whatever the client still shows. Then remove the server from the client so it stops trying to connect.

​
A tool returns an error

A tool result with isError: true means the call reached Melso but did not succeed. It can be a refusal (a stale version, an action the company cannot use, a record covered by an approved return), an error while running the action, or a failure at a service Melso depends on, such as the invoicing provider. Read the message the result returns first; it describes what went wrong. Then change the request, wait and try again, or ask Melso’s team. For an action that changes records, retry only the same request, as its tool page describes: for invoices issue, the same invoice and version. See Read MCP results. No tool approves, files or pays a tax return. If an assistant says it filed something, check the return in the Melso app: only the tax agency’s reference and receipt prove filing.