TypeScript Agent a MCP

Il generatore connection può connettere il tuo TypeScript Agent a un server MCP (sia TypeScript che Python).

Il generatore configura tutto il cablaggio necessario affinché il tuo agent possa scoprire e invocare gli strumenti del server MCP, sia quando viene distribuito su AWS (tramite Bedrock AgentCore) sia quando viene eseguito localmente.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto TypeScript con un componente Strands Agent
2. Un progetto con un componente server MCP (sia ts#mcp-server che py#mcp-server)
3. Entrambi i componenti creati con infra: agentcore

Utilizzo

Esegui il Generatore

Esegui questo generatore@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. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - connection
5. Compila i parametri richiesti
6. Clicca su Generate

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Seleziona il tuo progetto agent come sorgente e il tuo progetto server MCP come destinazione. Se i tuoi progetti contengono più componenti, specifica le opzioni sourceComponent e targetComponent per disambiguare.

Opzioni

Opzioni del generatore5 opzioni

sourceProjectObbligatoriostring

Il progetto sorgente

targetProjectObbligatoriostring

Il progetto di destinazione a cui connettersi

sourceComponentstring

Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come sorgente.

targetComponentstring

Il componente destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto destinazione, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come destinazione.

preferInstallDependenciesbooleanPredefinito: true

Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore crea un pacchetto condiviso agent-connection e modifica il codice del tuo agent:

• 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

Inoltre:

• Trasforma il file agent.ts del tuo agent per importare e utilizzare gli strumenti del server MCP
• Aggiorna il target dev dell’agent per dipendere dal target serve del server MCP
• Installa le dipendenze richieste

Utilizzo del Server MCP Connesso

Il generatore trasforma il file agent.ts del tuo agent per utilizzare gli strumenti del server 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],
  });
};

L’ID di sessione AgentCore viene propagato automaticamente al server MCP tramite l’header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, quindi create() non richiede argomenti: il server dell’agent associa la sessione della richiesta in entrata in un contesto AsyncLocalStorage (enterSessionContext nel router.ts generato, o runWithSessionId nel middleware di sessione A2A/AG-UI), e il fetch del client di connessione in agentcore-fetch.ts lo applica su ogni chiamata in uscita — garantendo coerenza per Bedrock AgentCore Observability.

Infrastruttura

Progetto di infrastruttura richiesto

I generatori agent, MCP server e Gateway forniscono i loro costrutti e moduli in packages/common, ma non creano un’applicazione da cui distribuirli — quindi packages/infra non esiste finché non lo generi. Esegui il generatore ts#infra (CDK) o il generatore terraform#project (Terraform) prima di modificare il file sottostante.

CDK

Dopo aver eseguito il generatore di connessione, devi concedere all’agent il permesso di invocare il server 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 collega le azioni di invocazione AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeForUser e InvokeAgentRuntimeWithWebSocketStream) sull’ARN del runtime del server MCP.

L’ARN del runtime AgentCore del server MCP viene automaticamente registrato nel namespace agentcore della Runtime Configuration dal costrutto CDK generato, in modo che l’agent possa scoprirlo a runtime.

Terraform

Dopo aver eseguito il generatore di connessione, devi concedere all’agent il permesso di invocare il server MCP nella tua configurazione Terraform:

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
}

L’ARN del runtime AgentCore del server MCP viene automaticamente registrato nel namespace agentcore della Runtime Configuration dal modulo Terraform generato, in modo che l’agent possa scoprirlo a runtime.

Sviluppo Locale

Il generatore configura il target dev dell’agent per:

1. Avviare automaticamente i server MCP connessi
2. Impostare LOCAL_DEV=true in modo che il client generato utilizzi il trasporto HTTP diretto invece di AgentCore

Esegui l’agent localmente con:

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>

Questo avvierà sia l’agent che tutti i server MCP connessi, con l’agent che si connette ai server MCP direttamente tramite HTTP sulle loro porte locali assegnate.