MCP

createMcpAdapter() makes an MCP server's tools available to your agent. Your code connects and authenticates the MCP client; the adapter supplies the server's tools to libfx, and the text of any resources and prompts you name as instructions.

Connect a server

Install the MCP client alongside libfx:

npm install libfx@0.0.17 @modelcontextprotocol/sdk@1

Set MCP_SERVER_URL to your server's Streamable HTTP endpoint. This example uses a server that accepts unauthenticated connections:

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
import { createFxAgent } from 'libfx'
import { createMcpAdapter } from 'libfx/mcp'

const client = new Client({ name: 'libfx-example', version: '1.0.0' })
await client.connect(new StreamableHTTPClientTransport(new URL(process.env.MCP_SERVER_URL)))

const mcp = await createMcpAdapter(client)
const agent = createFxAgent({ tools: mcp.tools, instructions: mcp.instructions })

try {
  const turn = agent.session().prompt('Use the available tools to show what this server offers.')
  for await (const event of turn) {
    if (event.type === 'text_delta') process.stdout.write(event.delta)
  }
} finally {
  await agent.close()
  await mcp.close() // closes the client
}

Close the agent first, so no turn is still calling the server. libfx also accepts clients connected over stdio instead of HTTP.

The adapter marks MCP tools idempotent: false, so when a crash cuts off an MCP call, libfx never runs it again; the model hears that it may have run. See Durability.

Authenticate the connection

For a server that accepts a bearer token, set MCP_SERVER_TOKEN and replace the transport above with:

const transport = new StreamableHTTPClientTransport(
  new URL(process.env.MCP_SERVER_URL),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.MCP_SERVER_TOKEN}` } } },
)
await client.connect(transport)

For OAuth, configure the MCP client's authProvider. Authentication belongs to that connection; the AI Gateway key is only for model requests.

Include resources and prompts

Pass resources and prompts to createMcpAdapter() to add their text to the agent's instructions. Use prefix to tell tools apart when you combine servers:

const github = await createMcpAdapter(githubClient, { prefix: 'github_', resources: ['repo://guidelines'] })
const linear = await createMcpAdapter(linearClient, { prefix: 'linear_' })

createFxAgent({
  tools: [...github.tools, ...linear.tools],
  instructions: [github.instructions, linear.instructions].join('\n\n'),
})

The model sees each tool as prefix followed by its MCP name, with any character other than a letter, digit, _, or - replaced by _, cut to 64 characters. Calls to the server keep the original name. An adapter's resource and prompt text must fit in 64 KiB. See the adapter options.

Observe calls

Enable instrumentation hooks on the agent to observe MCP calls alongside model and tool execution. Set the adapter's serverName to give those events a stable local identity; otherwise it uses the client's reported server name when available.

By default, hooks do not change remote MCP requests. Set propagateCorrelation: true on the adapter to send an opaque UUID in _meta["libfx/correlationId"] and record it in a mcp.request event. This does not send internal session or call ids or request progress notifications. Your app still owns connection authentication and event redaction.