Connectors

A connector is a ready-made MCP server for a common service — Gmail, Google Drive, SharePoint, Dropbox. The provider builds and maintains it, so there is nothing for you to host or register. Attach it to your Omniagent, supply the signed-in user's access token, and the agent can search their mail or read their calendar during the conversation.

Connectors vs. registered servers

Both end up as tools the agent can call. The difference is whether you have to register the server yourself.

Every connector acts as the signed-in user, never as your application. That is the point of them — the agent answers "what's on my calendar this afternoon" with that user's calendar.

If you are on Azure OpenAI

Connectors are unavailable, but the same services are still reachable — most publish their own MCP server, which you register like any other and attach with mcp.servers:

Register one with authorizationRequired: true and supply the user's OAuth token per session, exactly as described under per-user authorization. You run the same consent flow either way — only the field the ID goes in changes.

Available connectors

The ID is what you put in mcp.connectors.

Attach a connector

Connectors go in mcp.connectors, alongside any servers you registered in mcp.servers:

curl -X PATCH https://companion-api.napster.com/public/agents/agent_abc123 \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp": {
      "servers": ["inventory"],
      "connectors": ["gmail"]
    }
  }'

Then pass the user's access token when you open the session, keyed by the connector's ID:

curl -X POST https://companion-api.napster.com/public/agents/agent_abc123/connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelType": "webrtc",
    "mcp": {
      "authorizations": [
        {
          "mcpServerId": "gmail",
          "token": "ya29.a0AfH6..."
        }
      ]
    }
  }'

A connector always requires a token. Attaching one without an entry in mcp.authorizations fails the session with 400.

Access tokens and scopes

You run the OAuth flow. Napster never contacts Google, Microsoft or Dropbox — you register your own OAuth client with them, take the user through consent, hold the refresh token, and mint an access token per session. The token is used for that session and never stored.

The token has to carry the right scopes, or the connector's tools fail even though the session starts normally. Scopes are granted at consent time, so a missing one means sending the user back through the flow.

Scopes are defined by the service that issues the token — Google, Microsoft or Dropbox — not by Napster or by the connector. To find out what to ask for, see OpenAI's connectors documentation, which lists the scopes each connector's tools require.

Mint a fresh token per session rather than reusing a cached one — a conversation can outlive a short expiry, and the agent will start failing tool calls mid-session when it does.

Next steps