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

# 서버 개요

Mastra는 Agent, Workflow 및 기타 기능을 API 엔드포인트로 노출하는 HTTP 서버로 실행됩니다. 서버는 요청 라우팅, 미들웨어 실행, 인증 및 스트리밍 응답을 처리합니다.

> **정보:** 이 페이지에서는 `Mastra` 생성자에 전달하는 [`server`](https://mastra.zisheng.pro/ko/reference/configuration) 구성 옵션을 다룹니다. 자체 HTTP 서버(Hono, Express 등)로 Mastra를 실행하려면 [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)를 참조하세요.

## 서버 기능

- **[미들웨어](https://mastra.zisheng.pro/ko/docs/server/middleware)**: 인증, 로깅, CORS 또는 요청별 컨텍스트 주입에 대한 요청을 차단합니다.
- **[사용자 정의 API 경로](https://mastra.zisheng.pro/ko/docs/server/custom-api-routes)**: Mastra 인스턴스에 액세스할 수 있는 자체 HTTP 엔드포인트로 서버를 확장합니다.
- **[요청 컨텍스트](https://mastra.zisheng.pro/ko/docs/server/request-context)**: 런타임 조건에 따라 Agent, Tool 및 Workflow에 요청별 값을 전달합니다.
- **[서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)**: 생성된 서버 대신 Express, Hono 또는 자체 HTTP 서버를 사용하여 Mastra를 실행합니다.
- **[맞춤형 어댑터](https://mastra.zisheng.pro/ko/docs/server/custom-adapters)**: 공식적으로 지원되지 않는 프레임워크용 빌드 어댑터입니다.
- **[마스트라 클라이언트 SDK](https://mastra.zisheng.pro/ko/docs/server/mastra-client)**: 브라우저 또는 서버 환경에서 Agent, Workflow 및 Tool을 호출하기 위한 유형이 안전한 클라이언트입니다.
- **[A2A](https://mastra.zisheng.pro/ko/docs/agents/a2a)**: A2A Agent 카드, 작업 스트림, 푸시 알림을 통해 Agent를 노출합니다.
- **[입증](https://mastra.zisheng.pro/ko/docs/server/auth)**: JWT, Clerk, Supabase, Firebase, Auth0 또는 WorkOS를 사용하여 엔드포인트를 보호합니다.

## 구성

`Mastra` 생성자에 `server` 객체를 전달하여 서버를 구성합니다.

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to PORT env var or 4111
    host: '0.0.0.0', // Defaults to MASTRA_HOST env var or 'localhost'
  },
})
```

사용 가능한 전체 서버 옵션 목록은 [구성 레퍼런스](https://mastra.zisheng.pro/ko/reference/configuration)를 참조하세요.

## 서버 배포

Mastra 서버는 Node.js 호환 환경에 배포할 수 있습니다. [Mastra 플랫폼](https://mastra.zisheng.pro/ko/docs/mastra-platform/overview) 또는 자체 인프라를 사용하여 프로덕션에 배포하세요. 자세한 방법은 [배포 문서](https://mastra.zisheng.pro/ko/docs/deployment/overview)를 참조하세요.

## 서버 아키텍처

Mastra는 기반 HTTP 서버 프레임워크로 [Hono](https://hono.dev)를 사용합니다. `mastra build`를 사용하여 Mastra 애플리케이션을 빌드하면 `.mastra` 디렉터리에 Hono 기반 HTTP 서버가 생성됩니다. 서버는 다음을 제공합니다.

- 등록된 모든 Agent 및 Workflow에 대한 API 엔드포인트
- 맞춤형 API 경로 및 미들웨어
- 공급자 간 인증
- 런타임 구성을 위한 요청 컨텍스트
- 안전한 응답을 위한 스트림 데이터 수정

## REST API

사용 가능한 모든 엔드포인트는 <http://localhost:4111/api/openapi.json>의 OpenAPI 사양에서 살펴볼 수 있으며, 여기에는 각 엔드포인트와 요청 및 응답 스키마가 자세히 설명되어 있습니다. API를 대화형으로 살펴보려면 <http://localhost:4111/swagger-ui>의 Swagger UI를 방문하세요. 여기에서 엔드포인트를 살펴보고 브라우저에서 직접 테스트할 수 있습니다.

> **노트:** OpenAPI 및 Swagger 엔드포인트는 프로덕션에서 기본적으로 비활성화됩니다. 활성화하려면 [`server.build.openAPIDocs`](https://mastra.zisheng.pro/ko/reference/configuration)와 [`server.build.swaggerUI`](https://mastra.zisheng.pro/ko/reference/configuration)를 각각 `true`로 설정하세요.

## OpenAI 응답 API

Mastra는 Mastra Agent를 응답 API로 사용할 수 있는 OpenAI 호환 응답 및 대화 경로를 공개합니다. 이러한 경로는 Mastra Agent, Memory 및 스토리지에 대한 Agent 지원 어댑터이므로 요청은 원시 공급자 프록시로 작동하는 대신 선택한 Mastra Agent를 통해 실행됩니다.

이러한 API는 현재 실험적입니다.

요청을 처리할 Mastra Agent를 선택하려면 `agent_id`를 사용합니다. 최초 요청은 Agent를 직접 대상으로 하며, 저장된 후속 턴은 `previous_response_id`를 사용하여 이어갈 수 있습니다. `model`을 전달해 단일 요청에 한해 Agent에 구성된 Model을 재정의할 수도 있습니다. `model`을 생략하면 Mastra는 Agent에 이미 구성된 Model을 사용합니다. 응답 경로는 스트리밍, 함수 호출(Tool), `previous_response_id`를 통한 저장된 대화 이어가기, `conversation_id`를 통한 대화 스레드, `providerOptions`를 통한 Provider별 옵션 전달, `text.format`을 통한 JSON 출력을 지원합니다. 전체 요청 및 응답 규약은 [Responses API 레퍼런스](https://mastra.zisheng.pro/ko/reference/client-js/responses)와 [Conversations API 레퍼런스](https://mastra.zisheng.pro/ko/reference/client-js/conversations)를 참조하세요. 전체 HTTP 경로 목록은 [서버 경로](https://mastra.zisheng.pro/ko/reference/server/routes)를 참조하세요.

## 스트림 데이터 수정

스트리밍 Agent 응답 시 HTTP 계층은 시스템 Prompt, Tool 정의, API 키 및 각 청크의 유사한 데이터를 클라이언트에 보내기 전에 수정합니다. 이는 기본적으로 활성화되어 있습니다.

이 동작은 [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)를 사용할 때만 구성할 수 있습니다. 서버 어댑터에서도 스트림 데이터 수정은 기본적으로 활성화됩니다.

## 타입스크립트 구성

Mastra에는 최신 Node.js와 호환되는 `module` 및 `moduleResolution` 설정이 필요합니다. `CommonJS` 또는 `node` 같은 레거시 옵션은 지원되지 않습니다.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}
```

## 다음 단계

- 추가하다[middleware](https://mastra.zisheng.pro/ko/docs/server/middleware)
- 만들다[custom API routes](https://mastra.zisheng.pro/ko/docs/server/custom-api-routes)
- 추가하다[authentication](https://mastra.zisheng.pro/ko/docs/server/auth)
- [배포](https://mastra.zisheng.pro/ko/docs/deployment/overview)서버를 프로덕션으로