콘텐츠로 이동
@aws/nx-plugin
Blog

TypeScript Strands Agent에서 MCP로

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

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

사전 요구 사항

섹션 제목: “사전 요구 사항”

이 생성기를 사용하기 전에 다음을 확인하세요:

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

사용법

섹션 제목: “사용법”

생성기 실행

섹션 제목: “생성기 실행”
  1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
  2. VSCode에서 Nx 콘솔 열기
  3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
  4. 검색 @aws/nx-plugin - connection
  5. 필수 매개변수 입력
    • 클릭 Generate

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

    옵션

    섹션 제목: “옵션”
    매개변수 타입 기본값 설명
    sourceProject 필수 string - The source project
    targetProject 필수 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.

    생성기 출력

    섹션 제목: “생성기 출력”

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

    • 디렉터리packages/common/agent-connection
      • 디렉터리src
        • 디렉터리app
          • <mcp-server-name>-client.ts 연결된 MCP 서버를 위한 고수준 클라이언트
        • 디렉터리core
          • agentcore-mcp-client.ts SigV4/JWT 인증을 사용하는 저수준 AgentCore MCP 클라이언트
        • index.ts 모든 클라이언트 내보내기
      • project.json
      • tsconfig.json

    또한 다음을 수행합니다:

    • 에이전트의 agent.ts를 변환하여 MCP 서버의 도구를 가져오고 사용
    • 에이전트의 serve-local 대상을 업데이트하여 MCP 서버의 serve 대상에 의존하도록 설정
    • 필요한 의존성 설치

    연결된 MCP 서버 사용

    섹션 제목: “연결된 MCP 서버 사용”

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

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

    sessionId 매개변수는 호출자로부터 전달되어 Bedrock AgentCore Observability의 일관성을 보장합니다.

    인프라

    섹션 제목: “인프라”

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

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

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

    로컬 개발

    섹션 제목: “로컬 개발”

    생성기는 에이전트의 serve-local 대상을 다음과 같이 구성합니다:

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

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

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

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