TypeScript Agent to MCP

The connection generator can connect your TypeScript Agent to an MCP server (either TypeScript or Python).

The generator sets up all the necessary wiring so your agent can discover and invoke the MCP server’s tools, both when deployed to AWS (via Bedrock AgentCore) and when running locally.

Prerequisites

Before using this generator, ensure you have:

1. A TypeScript project with a Strands Agent component
2. A project with an MCP server component (either ts#mcp-server or py#mcp-server)
3. Both components created with infra: agentcore

Usage

Run the Generator

Run this generator@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection

yarn

$ yarn nx g @aws/nx-plugin:connection

npm

$ npx nx g @aws/nx-plugin:connection

bun

$ bunx nx g @aws/nx-plugin:connection

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - connection
5. Fill in the required parameters
6. Click Generate

Build your command5

sourceProjectRequired

targetProjectRequired

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runYou can also perform a dry-run to see what files would be changed

Select your agent project as the source and your MCP server project as the target. If your projects contain multiple components, specify the sourceComponent and targetComponent options to disambiguate.

Options

Generator Options5 options

sourceProjectRequiredstring

The source project

targetProjectRequiredstring

The target project to connect to

sourceComponentstring

The source component to connect from (component name, path relative to source project root, or generator id). Use '.' to explicitly select the project as the source.

targetComponentstring

The target component to connect to (component name, path relative to target project root, or generator id). Use '.' to explicitly select the project as the target.

preferInstallDependenciesbooleanDefault: true

Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator creates a shared agent-connection package and modifies your agent code:

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directoryapp

      • <mcp-server-name>-client-strands.ts High-level Strands client for the connected MCP server
    • Directorycore

      • agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
      • agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
      • agentcore-transport.ts Shared AgentCore transport plumbing
      • agentcore-mcp-transport.ts Framework-agnostic MCP transport
      • agentcore-mcp-client-strands.ts Strands MCP client wrapping the transport
    • index.ts Exports all clients
  • project.json
  • tsconfig.json

Additionally, it:

• Transforms your agent’s agent.ts to import and use the MCP server’s tools
• Updates the agent’s dev target to depend on the MCP server’s serve target
• Installs required dependencies

Using the Connected MCP Server

The generator transforms your agent’s agent.ts to use the MCP server’s tools:

packages/example/src/my-agent/agent.ts

import { Agent, tool } from '@strands-agents/sdk';
import { MyMcpServerClientStrands } from '@my-scope/agent-connection';

export const getAgent = async () => {
  const myMcpServerClient = await MyMcpServerClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myMcpServerClient],
  });
};

The AgentCore session ID is propagated to the MCP server automatically via the X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header, so create() takes no arguments: the agent server binds the inbound request’s session into an AsyncLocalStorage context (enterSessionContext in the generated router.ts, or runWithSessionId in the A2A/AG-UI session middleware), and the connection client’s fetch in agentcore-fetch.ts stamps it on every outbound call — ensuring consistency for Bedrock AgentCore Observability.

Infrastructure

Infrastructure project required

The agent, MCP server and Gateway generators vend their constructs and modules into packages/common, but they do not create an application to deploy them from — so packages/infra does not exist until you generate it. Run the ts#infra generator (CDK) or the terraform#project generator (Terraform) before editing the file below.

CDK

After running the connection generator, you need to grant the agent permission to invoke the MCP server:

packages/infra/src/stacks/application-stack.ts

const mcpServer = new MyMcpServer(this, 'MyMcpServer');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the MCP server
mcpServer.grantInvokeAccess(myAgent);

grantInvokeAccess wires up the AgentCore invoke actions (InvokeAgentRuntime, InvokeAgentRuntimeForUser and InvokeAgentRuntimeWithWebSocketStream) on the MCP server’s runtime ARN.

The MCP server’s AgentCore runtime ARN is automatically registered in the agentcore namespace of Runtime Configuration by the generated CDK construct, so the agent can discover it at runtime.

Terraform

After running the connection generator, you need to grant the agent permission to invoke the MCP server in your Terraform configuration:

packages/infra/src/main.tf

module "inventory_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
}

module "story_agent" {
  source = "../../common/terraform/src/app/agents/story-agent"
}

# Grant the agent permissions to invoke the MCP server
resource "aws_iam_policy" "agent_invoke_mcp" {
  name = "AgentInvokeMcpPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
      ]
      Resource = [
        module.inventory_mcp_server.agent_core_runtime_arn,
        "${module.inventory_mcp_server.agent_core_runtime_arn}/*",
      ]
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_mcp" {
  role       = module.story_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_mcp.arn
}

The MCP server’s AgentCore runtime ARN is automatically registered in the agentcore namespace of Runtime Configuration by the generated Terraform module, so the agent can discover it at runtime.

Local Development

The generator configures the agent’s dev target to:

1. Start the connected MCP server(s) automatically
2. Set LOCAL_DEV=true so the generated client uses direct HTTP transport instead of AgentCore

Run the agent locally with:

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

This will start both the agent and all connected MCP servers, with the agent connecting to the MCP servers directly via HTTP on their assigned local ports.