Other MCP clients

Any MCP client that can send an Authorization header over streamable HTTP can connect to VendOrca.

Before you start, issue a token on Agent access. The quickstart walks through it.

Claude Desktop#

Claude Desktop connects through the mcp-remote stdio bridge, which forwards requests to VendOrca with your token in the Authorization header. The bridge runs through npx, so Node.js must be installed.

1. Open claude_desktop_config.json.
2. Add a server entry. Replace <server-name> with a name such as vendorca and <token> with your token.
   jsonCopy

   {
     "mcpServers": {
       "<server-name>": {
         "command": "npx",
         "args": ["mcp-remote", "https://app.vendorca.com/api/v1/mcp", "--header", "Authorization:${AUTH_HEADER}"],
         "env": { "AUTH_HEADER": "Bearer <token>" }
       }
     }
   }

3. Restart Claude Desktop so it loads the new server. You see only the tools your token can call.

Keep Bearer <token> in the env block as shown. The args line reads it from AUTH_HEADER, which keeps the header value in one place. The file now holds your token: treat it like a password.

npx mcp-remote fetches the latest release of the bridge. Because the bridge handles your token, you can pin the version you have tested instead, for example mcp-remote@<version>.

Any other MCP client#

VendOrca's MCP server is a remote server with these properties:

Requests must send Content-Type: application/json and an Accept header that lists both application/json and text/event-stream. MCP clients send these for you. If you call the server by hand, add them yourself:

curl -s https://app.vendorca.com/api/v1/mcp \
  -H "Authorization: Bearer $VENDORCA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

If a client asks for a protocol version outside the list, the server refuses with HTTP 400 and JSON-RPC error -32602, message unsupported_protocol_version. The error's data.supported field lists the versions you can use.

Clients that need OAuth#

Some clients only connect remote servers through an OAuth-based "add connector" flow, with no way to set a request header. VendOrca authenticates with a bearer token in the Authorization header, so your client must be able to send one, directly or through a bridge such as mcp-remote.

Troubleshooting#

REST calls return the error as an HTTP status with a JSON body. Over MCP, a problem with the token itself comes back as an HTTP error. A problem with a single tool call, such as a missing scope, comes back as a tool result with isError: true whose text holds the same JSON error body. The Errors page lists every code.

401 unauthorized#

{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"unauthorized","data":{"request_id":"…"}}}

The token is missing, malformed, expired or revoked, or the account that issued it has been deactivated. Check that:

• the header reads Authorization: Bearer vo_agt.…, with the whole token and no line breaks or extra spaces inside it;
• the token still appears under Your tokens without a Revoked or Expired badge.

If either fails, issue a new token and update your client.

403 not_enabled#

Message: Agent access is not available for this credential.

The token is valid, but agent access is not available to the workspace right now. Agent access may be off or paused, it may need a Program Admin to review an updated disclosure, or the workspace plan may not include it. Ask a Program Admin to open Agent access and check the badge under This workspace. When access is restored, existing tokens work again without being reissued.

403 forbidden#

Message: This credential may not perform this operation. The token may not include the scope it needs, or the account that issued it may not have access to this data, for example because that account is not yet linked to a worker or billing entity. A program admin can check the account's access.

Common causes:

• The token lacks the scope for this operation. Invoices, expenses, assignments, program configuration and report queries need read:financial. See the scope table, then issue a new token with the right scopes.
• Your role can't open the matching page in the app. Report queries, approval statuses and program configuration are for staff roles.
• Your Worker or Billing Entity sign-in isn't linked to its record yet. Ask your Program Admin, who arranges the link with VendOrca support. See Worker and supplier sign-ins.

tools/list is empty#

tools/list shows only the tools your token can call right now. An empty list usually means one of these:

• Agent access is off or unavailable for the workspace. This has the same causes as not_enabled above.
• None of the token's scopes match an operation your role can use. For example, a worker token that carries only read:program has nothing to call. Issue a token with the scopes you need.

Next steps#

• Tokens and scopes
• Errors
• How agent access stays safe