Connections and OAuth

The @flue-eve/connections package bridges Flue MCP tools into Eve sessions and handles OAuth authorization flows.

Tool name mapping

Flue connections expose tools with mcp__ prefixed names. The mapper renames these to Eve's connection__ prefix:

This renaming happens automatically in mapFlueToEve(). The connection__ prefix is the convention Eve clients expect.

Why the prefix matters

Eve's tool call events include tool names in tool_call and tool_result events. The connection__ prefix tells Eve clients that this tool is a third-party connection — it affects how the UI renders tool invocations and how authorization flows are triggered.

OAuth flow

When a connection requires OAuth, the session automatically parks and resumes:

1. Agent calls a connection tool
2. Connection requires OAuth auth
3. compat-server emits authorization.required
4. Client opens the auth URL in a browser
5. User completes OAuth at the provider
6. Provider redirects to /eve/v1/oauth/callback
7. compat-server emits authorization.granted
8. Stream resumes, tools are available

Stream events

{"type":"authorization.required","data":{"connection":"github","authUrl":"https://github.com/login/oauth/authorize?..."},"streamIndex":3}
{"type":"authorization.granted","data":{"connection":"github"},"streamIndex":5}

Callback route

The compat-server automatically registers GET /eve/v1/oauth/callback when connections with OAuth are configured. The callback validates the OAuth code and state, exchanges it for a token (via @vercel/connect if available), and resumes the agent stream.

Configuring OAuth connections

With @vercel/connect (recommended)

import { defineFlueConnectionWithConnect } from '@flue-eve/connections/connect'

export const github = defineFlueConnectionWithConnect({
  name: 'github',
  // @vercel/connect manages tokens automatically
})

Manual OAuth

import { defineFlueConnection } from '@flue-eve/connections'

export const github = defineFlueConnection({
  name: 'github',
  auth: {
    type: 'oauth2',
    authorizationUrl: 'https://github.com/login/oauth/authorize',
    tokenUrl: 'https://github.com/login/oauth/access_token',
    clientId: process.env.GITHUB_CLIENT_ID,
    clientSecret: process.env.GITHUB_CLIENT_SECRET,
  },
  tools: ['search_repositories', 'get_file_contents'],
})

Security

• OAuth tokens are never sent to the browser
• The authorization.url event includes the auth URL but not the client secret
• The callback route validates state to prevent CSRF
• Proxied requests strip authorization headers to prevent token leakage

See connections guide for the full connection API and authoring connections for writing connection definitions.