---
title: "Add an MCP server"
method: POST
path: "/api/v1/org-mcp-servers"
tags: ["authed"]
---

# Add an MCP server

`POST /api/v1/org-mcp-servers`

## Request

- Base URL: `https://api.teaflask.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.teaflask.com/api/v1/org-mcp-servers`
- Auth: none declared

Adds a server with an access token or with no sign-in, once it has
answered with its tools; a server that doesn't answer adds nothing.

## Request body

- object
  - `display_name` string, required: The server's name in the dashboard; without a usable one, the server's own title or its host.
  - `url` string, password, required: The server's full address, starting with https://.
  - `token` string, password, nullable: An access token, sent as a bearer Authorization header.
  - `headers` object[], nullable: Instead of token: at most 5 headers carrying the access token.
    - `name` string, required: The header's name.
    - `value` string, password, required: The header's value.

## Response `201`

Successful Response

- OrgMcpServerResponse
  - `id` string, uuid, required: The server's id.
  - `handle` string, required: The server's short name in agent tool names; it never changes.
  - `display_name` string, required: The server's name in the dashboard.
  - `host` string, required: The host name of the server's address.
  - `state` 'active' | 'needs_reconnect' | 'failed', required
  - `last_error` string, nullable, required: Why the server last failed to connect, or null.
  - `sign_in` 'oauth' | 'token' | 'none', required
  - `signed_in_by` OrgMcpServerSignedInBy, required
    - `id` string, uuid, required: The person's id.
    - `name` string, required: The person's name, or their email without one.
  - `header_names` string[], required: The names of the headers carrying its access token.
  - `tool_count` integer, required: How many tools the server lists now.
  - `new_tool_count` integer, required: How many of those arrived after the server was added.
  - `skipped_tools` OrgMcpServerSkippedTool[], required: Tools the server lists that agents can't use, and why.
    - `name` string, required: The tool's name on the server.
    - `reason` string, required: Why agents can't use this tool.
  - `first_listed_at` string, date-time, required: When the server was added.
  - `tools_refreshed_at` string, date-time, required: When its tool list was last read.
  - `removed_at` string, date-time, nullable, required: When the server was removed, or null while it is live.
  - `created_at` string, date-time, required: When the server was created.
  - `version` integer, required: Pass back as expected_version when renaming the server.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: The server is already added
- `422`: The request was refused, or the server couldn't be connected
- `429`: Too many dials this minute or day
- `500`: Internal server error

---

[API](https://skmtc.dev/teaflask/apis/teaflask-api.md) - [All operations](https://skmtc.dev/teaflask/apis/teaflask-api/llms.txt) - [OpenAPI document](https://skmtc.dev/teaflask/apis/teaflask-api/revisions/d23e9286b847?raw)