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

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

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

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

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

Parameter	Type	Default	Description
sourceProject Required	string	-	The source project
targetProject Required	string	-	The target project to connect to
sourceComponent	string	-	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.
targetComponent	string	-	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.
preferInstallDependencies	boolean	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-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 (sessionId: string) => {
  const myMcpServerClient = await MyMcpServerClientStrands.create(sessionId);
  return new Agent({
    systemPrompt: '...',
    tools: [myMcpServerClient],
  });
};

The sessionId parameter is plumbed through from the caller, ensuring consistency for Bedrock AgentCore Observability.

Infrastructure

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);

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:InvokeAgent"
      Resource = 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.