Connections Guide

Connections bridge Flue MCP tools into Eve sessions as connection__* tools.

Why the connection__ prefix?

Flue connections expose tools with names like mcp__linear_search_issues. Eve's tool naming convention uses connection__ as the prefix. The mapper in @flue-eve/compat-server renames these automatically:

Flue tool:  mcp__linear_search_issues
Eve event:  tool_call { name: "connection__linear_search" }

This keeps Eve clients compatible with existing Eve tool name expectations.

Defining a connection

// src/connections/github.ts
import { defineFlueConnection } from '@flue-eve/connections'

export const github = defineFlueConnection({
  name: 'github',
  auth: { type: 'oauth' },
  tools: ['search_repositories', 'get_file_contents', 'list_issues'],
})

Connection registry

Register connections so the compat-server can filter and expose them:

// src/connections/index.ts
import { createConnectionRegistry } from '@flue-eve/connections'
import { github } from './github'
import { linear } from './linear'

export const connectionRegistry = createConnectionRegistry({
  connections: [github, linear],
})

The sidecar generated by npx flue-eve init automatically imports and passes the registry to eveCompat().

Connection types

Connection search

The connection__search tool is automatically exposed when connections are configured. It lets the agent discover available tools:

// The agent can call connection__search to list tools:
// → "connection__github_search"
// → "connection__github_get_file"
// → "connection__linear_search"

OAuth flow

When a connection requires OAuth, the session parks on authorization.required:

// Stream events:
// authorization.required { connection: "github", authUrl: "https://..." }
// User completes OAuth in browser
// GET /eve/v1/oauth/callback?code=...&state=...
// authorization.granted { connection: "github" }
// Stream resumes with connection tools available

The compat-server exposes an OAuth callback route automatically when connections with OAuth are configured.

@vercel/connect bridge

For @vercel/connect-compatible connections, use the optional bridge:

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

export const github = defineFlueConnectionWithConnect({
  name: 'github',
  // @vercel/connect handles token exchange and refresh
})

This is an optional peer dependency. Install @vercel/connect separately if you need OAuth token management.

Eve-style declarative connections

Place connection definitions in agent/connections/:

// agent/connections/linear.ts
export default {
  name: "linear",
  type: "mcp",
  auth: { type: "oauth" },
  tools: ["search_issues", "create_issue"],
}

Run npx flue-eve init --connections to generate Flue connection adapters.

Tool visibility

Connection tools appear in:

• GET /eve/v1/info — tools include connection__* entries
• Stream events — tool_call and tool_result use connection__* names
• connection__search — the agent discovers tools at runtime

Security

• Proxied requests strip authorization and cookie headers
• OAuth tokens are managed server-side in the connection adapter
• The @vercel/connect bridge handles token refresh transparently

See authoring connections for writing connection definitions, and connections and OAuth concept for the OAuth park/resume lifecycle.