TypeScript Strands Agent to MCP

The connection generator can connect your TypeScript Strands 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 computeType: BedrockAgentCoreRuntime

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.

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.ts High-level client for the connected MCP server
    • Directorycore

      • agentcore-mcp-client.ts Low-level AgentCore MCP client with SigV4/JWT authentication
    • 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 serve-local 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 { MyMcpServerClient } from ':my-scope/agent-connection';

export const getAgent = async (sessionId: string) => {
  const myMcpServerClient = await MyMcpServerClient.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 access to bedrock models
myAgent.agentCoreRuntime.addToRolePolicy(
  new PolicyStatement({
    actions: ['bedrock:InvokeModel', 'bedrock:InvokeModelWithResponseStream'],
    resources: ['arn:aws:bedrock:*:*:foundation-model/*', 'arn:aws:bedrock:*:*:inference-profile/*'],
  }),
);

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

The MCP server’s AgentCore runtime ARN is automatically registered in the connection 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 connection 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 serve-local target to:

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

Run the agent locally with:

pnpm

pnpm nx <agent-name>-serve-local <project-name>

yarn

yarn nx <agent-name>-serve-local <project-name>

npm

npx nx <agent-name>-serve-local <project-name>

bun

bunx nx <agent-name>-serve-local <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.