MCP Server a Database Relazionale

Il generatore connection collega un progetto TypeScript MCP Server a un progetto Relational Database, rendendo disponibile un client Prisma a tutti gli strumenti registrati all’interno di createServer.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto ts#mcp-server
2. Un progetto ts#rdb

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 MCP server come sorgente e il tuo progetto database relazionale come destinazione. Se il progetto contiene più componenti MCP server, specifica sourceComponent 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 modifica i seguenti file nella directory sorgente del tuo MCP server:

• Directorypackages/my-service/src/my-mcp

  • server.ts Client Prisma recuperato e disponibile per tutti gli strumenti registrati all’interno di createServer
  • Dockerfile Bundle CA RDS installato per connessioni SSL ad Aurora (solo quando l’infra dell’MCP server è agentcore-ecr)

Inoltre, il target <mcp-server-name>-dev viene aggiornato per dipendere dal target dev del database.

Utilizzo del Database negli Strumenti MCP

Il client Prisma viene recuperato all’interno di createServer ed è disponibile per tutti gli strumenti e le risorse registrati lì:

packages/my-service/src/my-mcp/server.ts

import { getPrisma as getMyDb } from '@my-scope/my-db';

export const createServer = async () => {
  const myDb = await getMyDb();
  myDb.$on('error', console.error);
  const server = new McpServer({ name: 'my-service', version: '1.0.0' });
  // register tools/resources that use myDb
  return server;
};

Database Multipli

Eseguire nuovamente il generatore con una destinazione diversa aggiunge il secondo database accanto al primo. Entrambi vengono recuperati all’interno di createServer:

packages/my-service/src/my-mcp/server.ts

export const createServer = async () => {
  const postgresDb = await getPostgresDb();
  const mysqlDb = await getMysqlDb();
  const server = new McpServer({ ... });
  // register tools using both clients
  return server;
};

Infrastruttura

Il costrutto MCP server generato implementa IGrantable e IConnectable, quindi puoi concedere l’accesso di rete e IAM al database direttamente sul costrutto.

CDK

packages/infra/src/stacks/application-stack.ts

import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
import { MyDatabase } from '@my-scope/common-constructs';

const db = new MyDatabase(this, 'Db', { vpc, ... });

const myMcpServer = new MyMcpServer(this, 'MyMcpServer', {
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
    vpc,
    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    securityGroups: [
      new SecurityGroup(this, 'MyMcpServerSecurityGroup', { vpc, allowAllOutbound: true }),
    ],
  }),
});

db.allowDefaultPortFrom(myMcpServer);
db.grantConnect(myMcpServer);

allowDefaultPortFrom apre la regola del security group in modo che il runtime MCP server possa raggiungere la porta del database. grantConnect concede il permesso IAM rds-db:connect al ruolo di esecuzione del server.

Terraform

Esegui l’MCP server all’interno dello stesso VPC del database, concedigli rds-db:connect tramite additional_iam_policy_statements e apri il percorso di rete con una coppia di regole di security group. Le risorse aws_vpc.main e aws_subnet sono definite nella guida di deployment del database:

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = aws_vpc.main.id
  database_subnet_ids = aws_subnet.database[*].id
  lambda_subnet_ids   = aws_subnet.private[*].id
}

module "my_mcp_server" {
  source     = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
  enable_vpc = true
  vpc_id     = aws_vpc.main.id
  subnet_ids = aws_subnet.private[*].id

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = ["rds-db:connect"]
      Resource = [
        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
      ]
    }
  ]
}

resource "aws_vpc_security_group_ingress_rule" "mcp_server_to_database" {
  description                  = "Allow the MCP server runtime to connect to the database"
  security_group_id            = module.my_database.security_group_id
  referenced_security_group_id = module.my_mcp_server.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

resource "aws_vpc_security_group_egress_rule" "mcp_server_to_database" {
  description                  = "Allow outbound traffic from the MCP server runtime to the database"
  security_group_id            = module.my_mcp_server.security_group_id
  referenced_security_group_id = module.my_database.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

appconfig_application_id/appconfig_application_arn provengono dall’applicazione AppConfig di configurazione runtime condivisa dichiarata una volta nel tuo modulo root, non dal modulo database. Quell’applicazione espone il namespace database per impostazione predefinita, quindi la voce di configurazione runtime del modulo database viene distribuita senza ulteriore configurazione.

Requisiti SSL per la Connessione Senza RDS Proxy

Il generatore di connessioni aggiorna il Dockerfile per installare il bundle CA di Amazon RDS in /usr/local/share/ca-certificates/rds-bundle.crt. Imposta NODE_EXTRA_CA_CERTS su quel percorso in modo che Node.js si fidi del certificato quando ci si connette senza RDS Proxy:

CDK

packages/infra/src/stacks/application-stack.ts

new MyMcpServer(this, 'MyMcpServer', {
  ...
  environmentVariables: {
    NODE_EXTRA_CA_CERTS: '/usr/local/share/ca-certificates/rds-bundle.crt',
  },
});

Terraform

packages/infra/src/main.tf

module "my_mcp_server" {
  ...
  env = {
    NODE_EXTRA_CA_CERTS = "/usr/local/share/ca-certificates/rds-bundle.crt"
  }
}

Per maggiori dettagli, consulta la documentazione SSL/TLS di Amazon RDS. Quando si utilizza RDS Proxy, non è necessario configurare NODE_EXTRA_CA_CERTS.

Sviluppo Locale

pnpm

pnpm nx <mcp-server-name>-dev <project-name>

yarn

yarn nx <mcp-server-name>-dev <project-name>

npm

npx nx <mcp-server-name>-dev <project-name>

bun

bunx nx <mcp-server-name>-dev <project-name>

Questo avvia l’MCP server e tutti i database connessi. La variabile d’ambiente LOCAL_DEV=true fa sì che ogni client Prisma si connetta al suo database Docker locale invece che ad Aurora.