TypeScript Agent에서 MCP로

connection 생성기는 TypeScript Agent를 MCP 서버(TypeScript 또는 Python)에 연결할 수 있습니다.

생성기는 에이전트가 MCP 서버의 도구를 검색하고 호출할 수 있도록 필요한 모든 연결을 설정합니다. AWS에 배포된 경우(Bedrock AgentCore를 통해)와 로컬에서 실행되는 경우 모두에서 작동합니다.

사전 요구 사항

이 생성기를 사용하기 전에 다음이 필요합니다:

1. Strands Agent 컴포넌트가 있는 TypeScript 프로젝트
2. MCP 서버 컴포넌트(ts#mcp-server 또는 py#mcp-server)가 있는 프로젝트
3. infra: agentcore로 생성된 두 컴포넌트

사용법

생성기 실행

이 제너레이터 실행@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. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - connection
5. 필수 매개변수 입력
6. 클릭 Generate

명령 구성하기5

sourceProject필수

targetProject필수

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-run어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

소스로 에이전트 프로젝트를 선택하고 타겟으로 MCP 서버 프로젝트를 선택합니다. 프로젝트에 여러 컴포넌트가 포함된 경우 sourceComponent 및 targetComponent 옵션을 지정하여 명확히 구분합니다.

옵션

제너레이터 옵션5 옵션

sourceProject필수string

소스 프로젝트

targetProject필수string

연결할 대상 프로젝트

sourceComponentstring

연결할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.

targetComponentstring

연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.

preferInstallDependenciesboolean기본값: true

생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

생성기는 공유 agent-connection 패키지를 생성하고 에이전트 코드를 수정합니다:

• 디렉터리packages/common/agent-connection

  • 디렉터리src

    • 디렉터리app

      • <mcp-server-name>-client-strands.ts High-level Strands client for the connected MCP server
    • 디렉터리core

      • 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

또한 다음을 수행합니다:

• 에이전트의 agent.ts를 변환하여 MCP 서버의 도구를 가져오고 사용
• 에이전트의 dev 타겟을 업데이트하여 MCP 서버의 serve 타겟에 의존
• 필요한 종속성 설치

연결된 MCP 서버 사용

생성기는 에이전트의 agent.ts를 변환하여 MCP 서버의 도구를 사용합니다:

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],
  });
};

AgentCore 세션 ID는 X-Amzn-Bedrock-AgentCore-Runtime-Session-Id 헤더를 통해 MCP 서버로 자동으로 전파되므로 create()는 인수를 받지 않습니다: 에이전트 서버는 인바운드 요청의 세션을 AsyncLocalStorage 컨텍스트에 바인딩하고(생성된 router.ts의 enterSessionContext 또는 A2A/AG-UI 세션 미들웨어의 runWithSessionId), 연결 클라이언트의 agentcore-fetch.ts에 있는 fetch가 모든 아웃바운드 호출에 이를 찍어냅니다 — Bedrock AgentCore Observability의 일관성을 보장합니다.

인프라

인프라 프로젝트 필요

에이전트, MCP 서버 및 Gateway 생성기는 구성 요소와 모듈을 packages/common으로 제공하지만, 이를 배포할 애플리케이션을 생성하지는 않습니다. 따라서 packages/infra는 생성하기 전까지 존재하지 않습니다. 아래 파일을 편집하기 전에 ts#infra 생성기(CDK) 또는 terraform#project 생성기(Terraform)를 실행하세요.

CDK

연결 생성기를 실행한 후 에이전트에 MCP 서버를 호출할 수 있는 권한을 부여해야 합니다:

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는 MCP 서버의 런타임 ARN에 AgentCore 호출 작업(InvokeAgentRuntime, InvokeAgentRuntimeForUser 및 InvokeAgentRuntimeWithWebSocketStream)을 연결합니다.

MCP 서버의 AgentCore 런타임 ARN은 생성된 CDK 구성에 의해 런타임 구성의 agentcore 네임스페이스에 자동으로 등록되므로 에이전트가 런타임에 이를 검색할 수 있습니다.

Terraform

연결 생성기를 실행한 후 Terraform 구성에서 에이전트에 MCP 서버를 호출할 수 있는 권한을 부여해야 합니다:

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
}

MCP 서버의 AgentCore 런타임 ARN은 생성된 Terraform 모듈에 의해 런타임 구성의 agentcore 네임스페이스에 자동으로 등록되므로 에이전트가 런타임에 이를 검색할 수 있습니다.

로컬 개발

생성기는 에이전트의 dev 타겟을 다음과 같이 구성합니다:

1. 연결된 MCP 서버를 자동으로 시작
2. LOCAL_DEV=true를 설정하여 생성된 클라이언트가 AgentCore 대신 직접 HTTP 전송을 사용

다음 명령으로 에이전트를 로컬에서 실행합니다:

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>

이렇게 하면 에이전트와 연결된 모든 MCP 서버가 시작되며, 에이전트는 할당된 로컬 포트에서 HTTP를 통해 MCP 서버에 직접 연결됩니다.