> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# NestJS 어댑터

그만큼`@mastra/nestjs`패키지는 Express 기반 NestJS 플랫폼으로 Mastra를 실행하기 위한 NestJS 모듈을 제공합니다.

v1은 의도적으로 Express만 지원합니다. Nest가 다른 HTTP 어댑터로 부트스트랩되면 `MastraModule`은 부분적인 통합을 시도하지 않고 시작 중에 오류를 발생시킵니다. 일반적인 어댑터 개념은 [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)를 참조하세요.

## 설치

NestJS 어댑터를 설치하고 앱이 Express 플랫폼을 사용하는지 확인하세요.

**npm**:

```bash
npm install @mastra/nestjs@latest
```

**pnpm**:

```bash
pnpm add @mastra/nestjs@latest
```

**Yarn**:

```bash
yarn add @mastra/nestjs@latest
```

**Bun**:

```bash
bun add @mastra/nestjs@latest
```

## 사용예

```typescript
import { Module } from '@nestjs/common'
import { MastraModule } from '@mastra/nestjs'
import { mastra } from './mastra'

@Module({
  imports: [
    MastraModule.register({
      mastra,
    }),
  ],
})
export class AppModule {}
```

> **노트:** `MastraModule`은 범용 컨트롤러(`@All('*')`)를 등록합니다. 애플리케이션 모듈보다 먼저 가져오면 관련 없는 경로를 가로채 404를 반환할 수 있습니다. 충돌을 방지하려면 `MastraModule`을 마지막에 가져오거나 전용 접두사(예: `/api/v1/mastra`) 아래에 마운트하세요.

```typescript
import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  await app.listen(3000)
}

bootstrap()
```

기본적으로 Mastra 경로는 `/api` 아래에 마운트됩니다. 이를 변경하려면 `prefix`를 사용하세요.

## 모듈 옵션

**mastra** (`Mastra`): Mastra 인스턴스

**prefix** (`string`): 경로 접두사(예: /api/v2) (Default: `` `/api` ``)

**rateLimitOptions** (`{ enabled?: boolean; defaultLimit?: number; windowMs?: number; generateLimit?: number }`): 요청 속도 제한 구성(기본적으로 활성화됨)

**shutdownOptions** (`{ timeoutMs?: number; notifyClients?: boolean }`): 정상 종료 구성

**bodyLimitOptions** (`{ maxSize?: number; maxFileSize?: number; tempDir?: string; allowedMimeTypes?: string[] }`): 요청 본문 크기 제한

**streamOptions** (`{ redact?: boolean; heartbeatMs?: number }`): 스트리밍 구성

**tracingOptions** (`{ enabled?: boolean; serviceName?: string }`): OpenTelemetry 추적 구성

**contextOptions** (`{ strict?: boolean; logWarnings?: boolean }`): 요청 컨텍스트 구문 분석 구성

**customRouteAuthConfig** (`Map<string, boolean>`): 경로별 인증 재정의입니다. 키는 METHOD:PATH 형식입니다.

**tools** (`Record<string, Tool>`): 서버에 등록된 Tool

**taskStore** (`InMemoryTaskStore`): A2A(Agent-to-Agent) 작업용 작업 저장소

**mcpOptions** (`{ serverless?: boolean; sessionIdGenerator?: () => string }`): MCP 전송 옵션

**auth** (`{ enabled?: boolean; allowQueryApiKey?: boolean }`): Mastra 토큰 인증을 활성화합니다. 기본적으로 비활성화되어 있습니다. 대부분의 NestJS 애플리케이션은 자체 인증 가드를 사용합니다. 이전 버전과의 호환성을 위한 쿼리 문자열 apiKey 인증은 명시적으로 활성화해야 합니다. (Default: `` `{ enabled: false }` ``)

## 비동기 등록

```typescript
import { Module } from '@nestjs/common'
import { ConfigModule, ConfigService } from '@nestjs/config'
import { MastraModule } from '@mastra/nestjs'
import { Mastra } from '@mastra/core/mastra'

@Module({
  imports: [
    ConfigModule.forRoot(),
    MastraModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        mastra: new Mastra({
          agents: {
            greeter: {
              name: 'greeter',
              description: 'Greets the user',
              model: config.get('MASTRA_MODEL', 'openai/gpt-5-mini'),
            },
          },
        }),
        prefix: config.get('MASTRA_PREFIX', '/api'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}
```

## 마스트라에 접근하기

서비스에서 `MASTRA` 토큰 또는 `MastraService`를 사용하세요.

```typescript
import { Injectable, Inject } from '@nestjs/common'
import { MASTRA, MastraService } from '@mastra/nestjs'
import type { Mastra } from '@mastra/core/mastra'

@Injectable()
export class AgentService {
  constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
}

@Injectable()
export class WorkflowService {
  constructor(private readonly mastraService: MastraService) {}
}
```

## MCP 경로

MCP 엔드포인트는 API 접두사 아래에 노출됩니다.

- `POST /api/mcp/:serverId/mcp`
- `GET /api/mcp/:serverId/sse`
- `POST /api/mcp/:serverId/messages`

## 건강 경로

인프라 호환성을 위해 운영 엔드포인트는 의도적으로 접두어가 붙지 않은 상태로 유지됩니다.

- `GET /health`
- `GET /ready`
- `GET /info`

## 관련된

- [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)
- [Mastra서버 참조](https://mastra.zisheng.pro/ko/reference/server/mastra-server)