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

# 코아 어댑터

그만큼`@mastra/koa`패키지는 Mastra를 실행하기 위한 서버 어댑터를 제공합니다.[코아](https://koajs.com). 일반적인 어댑터 개념(생성자 옵션, 초기화 흐름 등)은 다음을 참조하세요.[서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters).

## 설치

Koa 어댑터와 Koa 프레임워크를 설치합니다.

**npm**:

```bash
npm install @mastra/koa@latest koa koa-bodyparser
```

**pnpm**:

```bash
pnpm add @mastra/koa@latest koa koa-bodyparser
```

**Yarn**:

```bash
yarn add @mastra/koa@latest koa koa-bodyparser
```

**Bun**:

```bash
bun add @mastra/koa@latest koa koa-bodyparser
```

## 사용예

```typescript
import Koa from 'koa'
import bodyParser from 'koa-bodyparser'
import { MastraServer } from '@mastra/koa'
import { mastra } from './mastra'

const app = new Koa()
app.use(bodyParser())

const server = new MastraServer({ app, mastra })

await server.init()

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000')
})
```

## 생성자 매개변수

**app** (`Koa`): Koa 앱 인스턴스

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

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

**openapiPath** (`string`): OpenAPI 명세를 제공할 경로(예: /openapi.json) (Default: `''`)

**bodyLimitOptions** (`BodyLimitOptions`): 요청 본문 크기 제한

**streamOptions** (`StreamOptions`): 스트림 마스킹 구성입니다. true(기본값)이면 클라이언트로 보내기 전에 스트림 청크에서 민감한 데이터(시스템 Prompt, Tool 정의, API 키)를 마스킹합니다. (Default: `{ redact: true }`)

**customRouteAuthConfig** (`Map<string, boolean>`): 경로별 인증 재정의입니다. 키는 METHOD:PATH 형식입니다(예: GET:/api/health). 값이 false이면 경로가 공개되고, true이면 인증이 필요합니다.

**tools** (`ToolsInput`): 서버에서 사용할 수 있는 Tool

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

**mcpOptions** (`MCPOptions`): MCP 전송 옵션입니다. Cloudflare Workers 또는 Vercel Edge 같은 상태 비저장 환경에서는 serverless: true로 설정하세요.

## 오류 처리

Koa 어댑터는 Koa의 표준 오류 처리 패턴에 따라 경로 핸들러의 오류를 Koa의 미들웨어 체인을 통해 전파합니다. 이는 일반 Koa 오류 처리 미들웨어를 사용할 수 있음을 의미합니다.

```typescript
const app = new Koa()
app.use(bodyParser())

// Your error middleware catches errors from Mastra route handlers
app.use(async (ctx, next) => {
  try {
    await next()
  } catch (err) {
    ctx.status = err.status || 500
    ctx.body = { error: err.message }
    // Log, report to Sentry, etc.
  }
})

const server = new MastraServer({ app, mastra })
await server.init()
```

[`server.onError`](https://mastra.zisheng.pro/ko/reference/configuration) 훅도 지원됩니다. 구성하면 오류가 미들웨어로 전파되기 전에 호출되며, 훅의 응답이 직접 사용됩니다.

```typescript
const mastra = new Mastra({
  server: {
    onError: (err, c) => {
      console.error('Unhandled error:', err)
      return c.json({ error: err.message }, 500)
    },
  },
})
```

`init()`을 사용하면 전역 오류 처리 미들웨어도 안전망으로 등록됩니다. 이 미들웨어에 도달한 오류는 표준 Koa 규칙에 따라 `ctx.app.emit('error', err, ctx)`를 통해 방출됩니다.

## 원시 경로 보호

`requiresAuth` 같은 Mastra 관리 인증 및 경로 메타데이터가 필요하다면 [`registerApiRoute()`](https://mastra.zisheng.pro/ko/reference/server/register-api-route)를 사용하는 것이 좋습니다. 앱에 직접 마운트된 원시 Koa 경로에는 `createAuthMiddleware()`를 사용하세요.

```typescript
import Koa from 'koa'
import { createAuthMiddleware, MastraServer } from '@mastra/koa'
import { mastra } from './mastra'

const app = new Koa()
const server = new MastraServer({ app, mastra })

await server.init()

app.use(createAuthMiddleware({ mastra }))
app.use(async ctx => {
  if (ctx.path !== '/custom/protected') return

  const user = ctx.state.requestContext.get('user')
  ctx.body = { user }
})
```

## 수동 초기화

사용자 정의 미들웨어 순서가 필요하다면 `init()` 대신 각 메서드를 개별적으로 호출하세요. 자세한 내용은 [수동 초기화](https://mastra.zisheng.pro/ko/docs/server/server-adapters)를 참조하세요.

## 예

- [코아 어댑터](https://github.com/mastra-ai/mastra/tree/main/examples/server-koa-adapter): 기본 Koa 서버 설정

## 관련된

- [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters): 공유 어댑터 개념
- [Mastra서버 참조](https://mastra.zisheng.pro/ko/reference/server/mastra-server): 전체 API 참조
- [createRoute() 참조](https://mastra.zisheng.pro/ko/reference/server/create-route): 유형이 안전한 사용자 지정 경로 만들기