Remote MCP servers

MCP is the resource protocol, not an authentication kind. The trusted mcp provider acquires OAuth credentials for compatible Streamable HTTP endpoints. There are no runtime provider records to create.

Register the implementation

import { createMcpProvider } from '@hookfish/providers'

export default defineHookfishConfig({
  db,
  providers: {
    mcp: createMcpProvider(),
  },
})

Access a remote server

import { Hookfish } from '@hookfish/sdk'

const hookfish = new Hookfish({
  apiKey: process.env.HOOKFISH_API_KEY,
  baseUrl: 'https://broker.example.com/api',
})

await using mcp = await hookfish.mcp({
  connection: 'user/personal/notion/mcp',
  url: 'https://mcp.notion.com/mcp',
  returnTo: 'https://app.example.com/integrations',
})
const tools = await mcp.listTools()

hookfish.mcp() creates the MCP client, injects the current connection token, and connects it to the resource. await using closes the client when the current scope exits. When initial authorization is needed, Hookfish’s direct authorization_required error bubbles to your application error handler. When the MCP server returns 401, Hookfish starts fresh authorization and lets the same error bubble to your application error handler. By default, the client identifies itself with the @hookfish/sdk package name and version and negotiates the MCP protocol version automatically. Pass an unconnected MCP Client when you need custom client capabilities or options:

import { Client } from '@modelcontextprotocol/client'
import { Hookfish } from '@hookfish/sdk'

const client = new Client(
  { name: 'acme-integrations', version: '1.0.0' },
  { capabilities: { elicitation: {} } },
)

const hookfish = new Hookfish({
  apiKey: process.env.HOOKFISH_API_KEY,
  baseUrl: 'https://broker.example.com/api',
})

const mcp = await hookfish.mcp({
  connection: 'user/personal/notion/mcp',
  url: 'https://mcp.notion.com/mcp',
  client,
})

Install @modelcontextprotocol/client directly when you supply your own client. Hookfish connects and returns the same instance. The same initializer is also available under the provider namespace:

const mcp = await hookfish.provider.mcp({ connection, url })

The path ends in mcp because mcp is the provider implementation. user/personal is the namespace and notion identifies this resource for the generic provider. This cannot collide with a concrete Notion connection at user/personal/notion, whose provider ID is notion. The first access stores the normalized URL as immutable configuration and tracks requested and granted scopes separately. Reusing the path with a different URL returns connection_configuration_conflict. If the authorization server grants fewer scopes than requested, access that requires an omitted scope returns scope_not_granted. Hookfish does not restart consent automatically for a scope the provider already declined. See Errors for handling guidance.

Supplied credentials

The MCP AuthProvider sends an Authorization: Bearer header. It can return a supplied bearer token from a Hookfish secret connection instead of an OAuth connection. The fact that the application sends that credential to an MCP server does not change its Hookfish provider:

const authProvider = {
  token: async () =>
    (
      await hookfish.connections.access(
        'user/personal/notion-api-key/secret',
      )
    ).secret,
}

For a server that expects a different header, access the same secret and inject it through the transport request options:

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client'

const { secret } = await hookfish.connections.access(
  'user/personal/notion-api-key/secret',
)
const transport = new StreamableHTTPClientTransport(mcpUrl, {
  requestInit: { headers: { 'X-API-Key': secret } },
})

Client identity order

Hookfish discovers protected-resource and authorization-server metadata, requires PKCE S256, and then selects a client mechanism:

Use fixed MCP client credentials supplied in deployment configuration.
Use the deployment-level HTTPS Client ID Metadata Document when the server advertises CIMD support.
Use Dynamic Client Registration as a compatibility fallback.

The public CIMD URL is:

https://broker.example.com/api/connections/client-metadata.json

CIMD is stateless and shared at the deployment level. If DCR is required, the resulting client ID and encrypted client secret belong to the individual connection. Hookfish does not create a reusable runtime provider record.

Discovery requirements

The MCP resource must publish protected-resource metadata naming an authorization server. The authorization server must advertise an issuer, authorization endpoint, token endpoint, and PKCE S256. Hookfish validates a callback issuer when it is present.

Every unready access returns a newly generated authorization URL. Call connections.authorize() after an upstream rejection to start a fresh flow even when the stored credential has not reached its recorded expiration.

Get started

Store secrets

Integrate

Deploy

Secure and scale

Operate

Remote MCP servers

Register the implementation

Access a remote server

Supplied credentials

Client identity order

Discovery requirements

​Register the implementation

​Access a remote server

​Supplied credentials

​Client identity order

​Discovery requirements

Register the implementation

Access a remote server

Supplied credentials

Client identity order

Discovery requirements