Remote MCP servers behind `@requires` never yield tools — auth headers are not sent on the `tools/list` handshake

[TimZechmeister-NTTDATA]

Problem

buildMcpToolsFromConnection() authenticates MCP tool calls but not the handshake that discovers them. Against any MCP server that requires an authenticated user, client.getTools() is answered with 401, so the agent starts up with zero tools from that connection.

The failure is silent in the common case: buildTools catches the error, logs a warning, and the agent runs — it just can never use the service. Nothing in the A2A response indicates that half its capabilities are missing.

Reproduction

Any CAP service annotated @mcp plus @requires: 'authenticated-user', consumed by an agent via @agent.connect, with a valid token forwarded through a destination. Result:

MCPClientError: Authentication failed for HTTP server "bookshop_mcp"
  {"jsonrpc":"2.0","error":{"code":-32001,
   "message":"Authorization error (401): Not authorized to access BooksService."}}

(The SSE fallback then also fails with Non-200 status code (404), since @cap-js/mcp only serves streamable HTTP.)

I verified that the request is otherwise sound: the identical URL and token succeed when the same headers are passed in mcpServers.

Root cause

Introduced by #211 (feat: downstream @mcp and @agent services), which moved header resolution from connection setup to beforeToolCall:

   const client = new MultiServerMCPClient({
     mcpServers: {
-      [serviceName]: {
-        url: mcpUrl,
-        ...(Object.keys(headers).length ? { headers } : {}),
-      },
+      [serviceName]: { url: mcpUrl },
     },
+    beforeToolCall: async () => ({ headers: await resolveHeaders() }),
   })

Resolving headers per call is right — cached graphs outlive the tokens baked into them. But beforeToolCall is only consulted from _callTool() in @langchain/mcp-adapters (dist/tools.js:367). getTools() goes through initializeConnections(), where headers come from customTransportOptions (dist/client.js:316), which is undefined here. So the handshake goes out unauthenticated and no tool ever reaches the point where beforeToolCall would apply.

The same commit also changed the destructuring at mcp-tools.js:114 to const { url } = …, discarding the headers that resolveDestination() still returns.

Second, latent issue

Once the handshake is fixed, a follow-up surfaces. mcpServers entries omit transport. That is fine for the initial connection, because client.js:394 passes the string literal "http" into createClient() when the type is null:

if (transportType === "http" || transportType == null) try {
  const client = await this.#clientConnections.createClient("http", serverName, connection)

The inferred type is never written back into the stored connection options. When beforeToolCall returns headers, tools.js:374-376 forks the client, and the fork reads the type back out of that stored config (connection.js:104):

const type = connection.transportOptions.type ?? connection.transportOptions.transport

Both fields are undefined, and createClient() validates strictly (connection.js:31), so:

ToolException: Error calling tool list_books: Error: Invalid transport type: undefined

Discovery succeeds, so the agent looks healthy until someone actually calls a tool — at which point the model receives the exception as a tool error. Before #211 there was no fork, so this could not surface.

Proposed fix

In srv/handlers/mcp-tools.js:

const initialHeaders = await resolveHeaders()

const client = new MultiServerMCPClient({
  mcpServers: {
    [serviceName]: { transport: "http", url: mcpUrl, headers: initialHeaders },
  },
  beforeToolCall: async () => ({ headers: await resolveHeaders() }),
})

sub-agent-tools.js already does exactly this — const initialHeaders = await resolveHeaders() at line 277, used for the agent-card fetch at line 280, with fresh headers per request at line 294. Only the MCP path was left behind.

I'd also suggest an integration test with an MCP server behind @requires. The existing ones use xflights, which is unsecured, and destination-guide-service is in-process — neither exercises the remote + authenticated combination, which is why both defects went unnoticed.

Environment

@cap-js/agents 0.9.1 · @langchain/mcp-adapters 1.1.4 · @modelcontextprotocol/sdk 1.30.0 · @sap/cds 10.0.6
Server: @cap-js/mcp 1.4.3 (also reproduces on 1.2.0), SAP BTP Cloud Foundry, IAS auth

Reported per CONTRIBUTING.md; happy to provide further details if useful.

[github-actions]

👋 Hello @TimZechmeister-NTTDATA, thank you for submitting this issue. Our team is reviewing your report and will follow up with you as soon as possible.

[Akatuoro]

Hi @TimZechmeister-NTTDATA ,
Thanks for reporting! I was able to reproduce the issue. The fix will be a bit more complicated though as the MCP tool list can depend on the user authorization. So if we simply enter initialHeaders, it will take the user authorizations of whoever sends the first request. Looking into options.

reproduction script

// Reproduction script for issue #48
// Run with: cds bind --exec --profile hybrid -- node repro-48.js
//
// Demonstrates that tools/list is sent without auth headers (bug), causing a 401
// from CatalogService (@requires: 'authenticated-user') on bookshop-mcp-srv.
// Then shows the fix: passing initial headers on the mcpServers entry.

const MCP_URL = '<base>/mcp/catalog'

// Obtain a real client-credentials token from the XSUAA bound via cds bind.
async function fetchToken() {
  const vcap = JSON.parse(process.env.VCAP_SERVICES ?? '{}')
  const xsuaa = vcap.xsuaa?.[0]?.credentials ?? vcap['user-provided']?.[0]?.credentials
  if (!xsuaa) throw new Error('No XSUAA credentials in VCAP_SERVICES — run via: cds bind --exec --profile hybrid -- node repro-48.js')

  const { url, clientid, clientsecret } = xsuaa
  const tokenUrl = `${url}/oauth/token`
  const res = await fetch(tokenUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${clientid}:${clientsecret}`).toString('base64')}`,
    },
    body: 'grant_type=client_credentials',
  })
  if (!res.ok) throw new Error(`Token fetch failed: ${res.status} ${await res.text()}`)
  const { access_token } = await res.json()
  return access_token
}

const { MultiServerMCPClient } = await import('@langchain/mcp-adapters')

const token = await fetchToken()
console.log('Obtained XSUAA client-credentials token.')
console.log('MCP server:', MCP_URL)

// --- BUG: current mcp-tools.js behaviour ---
// headers are only passed via beforeToolCall, which is NOT called by getTools().
console.log('\n[BUG] client with no initial headers (mirrors current mcp-tools.js):')
const bugClient = new MultiServerMCPClient({
  mcpServers: {
    CatalogService: { url: MCP_URL },
  },
  beforeToolCall: async () => ({ headers: { Authorization: `Bearer ${token}` } }),
})
try {
  const tools = await bugClient.getTools()
  console.log(`  Got ${tools.length} tools — unexpected success`)
} catch (err) {
  console.error('  tools/list failed (expected):', err.message)
}

// --- FIX: proposed in issue #48 ---
// Pass initial headers on the mcpServers entry so getTools() authenticates.
console.log('\n[FIX] client with initial headers on mcpServers entry:')
const fixClient = new MultiServerMCPClient({
  mcpServers: {
    CatalogService: {
      transport: 'http',
      url: MCP_URL,
      headers: { Authorization: `Bearer ${token}` },
    },
  },
  beforeToolCall: async () => ({ headers: { Authorization: `Bearer ${token}` } }),
})
try {
  const tools = await fixClient.getTools()
  console.log(`  Got ${tools.length} tools:`, tools.map(t => t.name))
} catch (err) {
  console.error('  tools/list failed (unexpected):', err.message)
}