---
title: "Save a server into a project"
method: POST
path: "/projects/{projectId}/servers"
tags: ["Servers"]
---

# Save a server into a project

`POST /projects/{projectId}/servers`

Creates a saved MCP server and responds `201` with its detail. This is the provisioning entry point: every eval, host and environment route addresses servers that were created here. Names are unique per workspace, so a clash responds `409` rather than silently returning the existing row. Secret-bearing fields (`env`, `headers`, `clientSecret`) are encrypted at rest and never returned by any read.

## Path parameters

- `projectId` string, required

## Request body

- ProjectServerCreateRequest — Creates a saved server in the project. Server names are unique per workspace — a clash responds `409`. Scope comes from the path: `projectId`, `serverId` and `workspaceId` are rejected in the body.
  - `name` string, required
  - `enabled` boolean, required
  - `transportType` 'stdio' | 'http', required
  - `command` string — stdio transport only.
  - `args` string[]
  - `env` object — Stored encrypted; never returned by any read.
  - `url` string, uri — http transport only.
  - `headers` object — Stored encrypted; never returned by any read.
  - `hasBearerToken` boolean
  - `timeout` number
  - `clientCapabilities` unknown
  - `useOAuth` boolean
  - `oauthScopes` string[]
  - `clientId` string
  - `oauthResourceUrl` string
  - `oauthProtocolMode` string
  - `oauthProtocolVersion` string
  - `oauthRegistrationStrategy` string
  - `xaaAuthzIssuer` string
  - `xaaAllowPathScopedIssuer` boolean
  - `oauthAllowPathScopedIssuer` boolean
  - `useXaa` boolean
  - `authServerMode` 'mcpjam' | 'own'
  - `xaaSubject` string
  - `xaaEmail` string
  - `xaaIdentityAssertionFormat` string
  - `xaaClientAuth` string
  - `authMethod` string
  - `registrationMode` string
  - `clientSecret` string — Stored encrypted; never returned. Reads expose only `hasClientSecret`.

## Response `201`

The server was created.

- ProjectServer — A saved MCP server, projected toward the hosted (HTTP) shape. STDIO command/args/env and raw headers are never exposed.
  - `id` string, required
  - `projectId` string, nullable
  - `name` string, required
  - `enabled` boolean, required
  - `transportType` string, required
  - `url` string, nullable — Endpoint for HTTP-transport servers; `null` for stdio.
  - `useOAuth` boolean, required
  - `hasClientSecret` boolean, required
  - `oauthScopes` string[]
  - `createdAt` number, nullable — Epoch milliseconds.
  - `updatedAt` number, nullable

## Other responses

- `400` — Malformed body or parameters.
- `401` — Missing, invalid, revoked, or orphaned key (`UNAUTHORIZED`) — or the **target MCP server** needs an OAuth grant (`OAUTH_REQUIRED`), which is a property of the server, not your key.
- `403` — Key is valid but not allowed to do this.
- `404` — Unknown project, server, or resource.
- `409` — The resource is not in a state that accepts this write — a stale `expectedRevision`, a duplicate name, or an environment that cannot currently be launched. The request was well-formed; re-read the resource and retry.
- `429` — Per-key rate limit exceeded (60 requests/minute sustained, bursts up to 10). Honor `Retry-After` and back off with jitter.
- `500` — Something failed on MCPJam's side.
- `502` — Could not connect to the target MCP server.

---

[API](https://skmtc.net/mcpjam/apis/mcpjam-api.md) · [All operations](https://skmtc.net/mcpjam/apis/mcpjam-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mcpjam/mcpjam-api/versions/b767df188d0c/schema)