> ## Documentation Index > Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt > Use this file to discover all available pages before exploring further. # Add an MCP server to the organization's catalog > Adds an MCP server, remote (http) or local (stdio), to the organization's catalog and enables it on every project of the organization; returns the server with 201. Use this tool when you need to: - Add a remote MCP server by its https URL so the organization's tasks can use it - Add a local MCP server run from a pinned npm or PyPI package in each task's VM Examples: - POST /orgs/{orgID}/mcp-servers {"kind": "http", "url": "https://mcp.acme.dev/mcp", "key": "acme", "display_name": "Acme", "required": false} - POST /orgs/{orgID}/mcp-servers {"kind": "stdio", "key": "acme-local", "display_name": "Acme Local", "required": false, "runtime": "npx", "package": "@acme/mcp-server", "version": "1.4.2", "args": ["--read-only"], "env": {"ACME_TOKEN": {"kind": "secret"}, "ACME_REGION": {"kind": "plain", "value": "eu"}}} Hints: - kind, key (a lowercase letter, then up to 31 lowercase letters, digits, _ or -), display_name (1 to 100 characters) and required are required; http adds url (https, up to 2048), optional non-secret headers and optional auth, whose only value is static_secret (any other is a plain 422); stdio adds runtime (npx, uvx or python), package, an exact version, args (at most 64) and env (plain values or secret variables). - A remote server's URL is probed and the auth it finds stored, or static_secret when auth is static_secret. A local server is validated, never run, and its auth derived from its declared secret variables. - The server is enabled on every current project of the organization, and every project created later, with its default credential policy: the task creator's connection for a server that needs a credential, none otherwise. required true keeps a task from being created until its connection can be used. - Use probeMcpServer instead to see how a URL authenticates without adding it, and installDirectoryIntegration for an integration of Aether's directory. - Org admins only: owners and admins of the organization in the path; a member, viewer or billing member is refused with 403 org_role_insufficient and a non-member with 403 org_membership_required. - Refused with 409 mcp_server_key_taken for a key another server of the organization uses, 422 mcp_server_key_reserved for the key of one of Aether's servers or a directory integration, 422 mcp_server_api_key_not_applicable for auth static_secret on a server that asks for no credential, 422 with the field's code (mcp_server_url_invalid, mcp_server_headers_invalid, mcp_server_runtime_invalid, mcp_server_package_invalid, mcp_server_version_unpinned, mcp_server_args_invalid, mcp_server_env_invalid and the like) and 422 with the probe's code when the URL cannot be probed. ## OpenAPI ````yaml api-reference/openapi.json POST /orgs/{orgID}/mcp-servers openapi: 3.1.0 info: title: Aether API version: 0.1.0 servers: - url: https://api.runaether.dev security: - bearerAuth: [] paths: /orgs/{orgID}/mcp-servers: post: tags: - mcp-servers summary: Add an MCP server to the organization's catalog description: >- Adds an MCP server, remote (http) or local (stdio), to the organization's catalog and enables it on every project of the organization; returns the server with 201. Use this tool when you need to: - Add a remote MCP server by its https URL so the organization's tasks can use it - Add a local MCP server run from a pinned npm or PyPI package in each task's VM Examples: - POST /orgs/{orgID}/mcp-servers {"kind": "http", "url": "https://mcp.acme.dev/mcp", "key": "acme", "display_name": "Acme", "required": false} - POST /orgs/{orgID}/mcp-servers {"kind": "stdio", "key": "acme-local", "display_name": "Acme Local", "required": false, "runtime": "npx", "package": "@acme/mcp-server", "version": "1.4.2", "args": ["--read-only"], "env": {"ACME_TOKEN": {"kind": "secret"}, "ACME_REGION": {"kind": "plain", "value": "eu"}}} Hints: - kind, key (a lowercase letter, then up to 31 lowercase letters, digits, _ or -), display_name (1 to 100 characters) and required are required; http adds url (https, up to 2048), optional non-secret headers and optional auth, whose only value is static_secret (any other is a plain 422); stdio adds runtime (npx, uvx or python), package, an exact version, args (at most 64) and env (plain values or secret variables). - A remote server's URL is probed and the auth it finds stored, or static_secret when auth is static_secret. A local server is validated, never run, and its auth derived from its declared secret variables. - The server is enabled on every current project of the organization, and every project created later, with its default credential policy: the task creator's connection for a server that needs a credential, none otherwise. required true keeps a task from being created until its connection can be used. - Use probeMcpServer instead to see how a URL authenticates without adding it, and installDirectoryIntegration for an integration of Aether's directory. - Org admins only: owners and admins of the organization in the path; a member, viewer or billing member is refused with 403 org_role_insufficient and a non-member with 403 org_membership_required. - Refused with 409 mcp_server_key_taken for a key another server of the organization uses, 422 mcp_server_key_reserved for the key of one of Aether's servers or a directory integration, 422 mcp_server_api_key_not_applicable for auth static_secret on a server that asks for no credential, 422 with the field's code (mcp_server_url_invalid, mcp_server_headers_invalid, mcp_server_runtime_invalid, mcp_server_package_invalid, mcp_server_version_unpinned, mcp_server_args_invalid, mcp_server_env_invalid and the like) and 422 with the probe's code when the URL cannot be probed. operationId: createMcpServer parameters: - in: path name: orgID required: true schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/McpServerRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/McpServer' description: Created '400': content: application/json: schema: $ref: '#/components/schemas/McpServersErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/McpServersErrorResponse' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/OrgAuthorizationErrorResponse' description: Forbidden '409': content: application/json: schema: $ref: '#/components/schemas/McpServerErrorResponse' description: Conflict '422': content: application/json: schema: anyOf: - $ref: '#/components/schemas/McpServersErrorResponse' - $ref: '#/components/schemas/McpServerErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/McpServersErrorResponse' description: Internal Server Error components: schemas: McpServerRequest: discriminator: mapping: http: '#/components/schemas/McpHTTPServerRequest' stdio: '#/components/schemas/McpStdioServerRequest' propertyName: kind oneOf: - $ref: '#/components/schemas/McpHTTPServerRequest' - $ref: '#/components/schemas/McpStdioServerRequest' McpServer: discriminator: mapping: http: '#/components/schemas/McpHTTPServer' stdio: '#/components/schemas/McpStdioServer' propertyName: kind oneOf: - $ref: '#/components/schemas/McpHTTPServer' - $ref: '#/components/schemas/McpStdioServer' McpServersErrorResponse: additionalProperties: false properties: code: enum: - account_deleting - aether_inference_unavailable - aether_inference_unserved - agent_connector_not_found - agent_default_project_archived - bad_gateway - bad_request - conflict - connection_agent_only - connection_harness_mismatch - connection_not_held - control_forbidden - default_skill_required - forbidden - gateway_timeout - gone - integration_auth_unexpected - integration_not_in_directory - integration_shape_changed - internal_error - mcp_connection_github_not_connected - mcp_connection_oauth_not_accepted - mcp_connection_org_not_offered - mcp_connection_secret_invalid - mcp_connection_server_changed - mcp_connection_static_secret_not_accepted - mcp_credential_policy_not_applicable - mcp_credential_policy_org_unavailable - mcp_credential_policy_required - mcp_oauth_app_auth_method_unsupported - mcp_oauth_app_invalid - mcp_oauth_app_issuer_invalid - mcp_oauth_app_required - mcp_oauth_not_advertised - mcp_oauth_pkce_unsupported - mcp_oauth_registration_failed - mcp_repo_config_invalid - mcp_server_address_refused - mcp_server_aether_managed - mcp_server_api_key_not_applicable - mcp_server_args_invalid - mcp_server_auth_discovery_failed - mcp_server_auth_unsupported - mcp_server_directory_managed - mcp_server_directory_moved - mcp_server_display_name_invalid - mcp_server_env_invalid - mcp_server_headers_invalid - mcp_server_key_invalid - mcp_server_key_reserved - mcp_server_key_taken - mcp_server_kind_change_refused - mcp_server_not_from_directory - mcp_server_not_mcp - mcp_server_package_invalid - mcp_server_plugin_bundled - mcp_server_plugin_off - mcp_server_response_too_large - mcp_server_return_to_invalid - mcp_server_runtime_invalid - mcp_server_switched_off - mcp_server_unreachable - mcp_server_url_invalid - mcp_server_version_unpinned - method_not_allowed - not_acceptable - not_found - not_implemented - org_role_insufficient - org_suspended - payment_required - plugin_moved - plugin_name_taken - plugin_request_invalid - plugin_server_key_reserved - plugin_server_key_taken - plugin_server_probe_failed - plugin_server_required - plugin_skill_invalid - plugin_source_address_refused - plugin_source_empty - plugin_source_invalid - plugin_source_not_found - plugin_source_not_public - plugin_source_too_large - plugin_source_unreachable - plugin_source_unsupported - plugin_switched_off - plugin_undeliverable - precondition_failed - rate_limited - request_canceled - request_timeout - request_too_large - service_unavailable - skill_slug_reserved - unauthenticated - unsupported_media_type - validation_failed minLength: 1 type: string error: minLength: 1 type: string errors: items: $ref: '#/components/schemas/ErrorDetail' type: array required: - error - code type: object OrgAuthorizationErrorResponse: additionalProperties: false properties: code: enum: - org_membership_required - org_role_insufficient - org_suspended - account_deleting - agent_host_route_not_allowed - credential_kind_not_admitted type: string error: minLength: 1 type: string required: - error - code type: object McpServerErrorResponse: additionalProperties: false properties: code: enum: - mcp_server_key_invalid - mcp_server_key_reserved - mcp_server_key_taken - mcp_server_display_name_invalid - mcp_server_url_invalid - mcp_server_runtime_invalid - mcp_server_package_invalid - mcp_server_version_unpinned - mcp_server_args_invalid - mcp_server_env_invalid - mcp_server_kind_change_refused - mcp_server_address_refused - mcp_server_unreachable - mcp_server_not_mcp - mcp_server_auth_unsupported - mcp_server_auth_discovery_failed - mcp_server_response_too_large - mcp_credential_policy_required - mcp_credential_policy_not_applicable - mcp_credential_policy_org_unavailable - mcp_server_api_key_not_applicable - mcp_connection_static_secret_not_accepted - mcp_connection_secret_invalid - mcp_connection_server_changed - mcp_server_aether_managed - mcp_connection_github_not_connected - mcp_connection_org_not_offered - mcp_server_headers_invalid - mcp_connection_oauth_not_accepted - mcp_oauth_not_advertised - mcp_oauth_pkce_unsupported - mcp_oauth_app_required - mcp_oauth_registration_failed - mcp_server_plugin_bundled - mcp_server_plugin_off - mcp_repo_config_invalid - mcp_oauth_app_issuer_invalid - mcp_oauth_app_invalid - mcp_oauth_app_auth_method_unsupported - mcp_server_directory_managed - mcp_server_not_from_directory - mcp_server_directory_moved - integration_not_in_directory - integration_shape_changed - mcp_server_switched_off - mcp_server_return_to_invalid type: string error: minLength: 1 type: string required: - error - code type: object McpHTTPServerRequest: additionalProperties: false properties: auth: description: >- static_secret: authenticate with an API key sent as a bearer token instead of the OAuth the server advertises; refused with mcp_server_api_key_not_applicable for a server that asks for no credential. Omitted: the auth the probe finds. The URL is probed again when it changed or when a static_secret server stops being one; a server's connections go when its URL or auth changes. enum: - static_secret type: string display_name: maxLength: 100 minLength: 1 type: string headers: additionalProperties: type: string description: >- Non-secret headers sent upstream on every request, as a local .mcp.json entry's headers: GitHub's X-MCP-Toolsets, for one. Never Authorization, Accept, Content-Type, Last-Event-ID or an Mcp-* header. Omitted: none. One of Aether's own servers keeps the headers Aether fixes for it (X-MCP-Readonly on github_readonly). type: object key: pattern: ^[a-z][a-z0-9_-]{0,31}$ type: string kind: enum: - http type: string required: description: >- True: a task is not created until the connection its project's credential policy names can be used, and a turn that cannot reach the server fails, naming it. False, the Integrations tab's default: a task whose connection cannot be used starts without the server, and its agent is not given it. type: boolean url: maxLength: 2048 minLength: 1 pattern: ^https:// type: string required: - kind - url - key - display_name - required type: object McpStdioServerRequest: additionalProperties: false properties: args: description: Arguments after the package, at most 64 of at most 1024 bytes each. items: type: string type: array display_name: maxLength: 100 minLength: 1 type: string env: additionalProperties: $ref: '#/components/schemas/McpStdioEnvValue' description: >- Declared variables: a plain value, or a secret whose value each connection holds. Names are shell identifiers, never PATH, HOME, npm_config_cache or UV_CACHE_DIR. A changed runtime, package, version, args or env deletes the server's connections. type: object key: pattern: ^[a-z][a-z0-9_-]{0,31}$ type: string kind: enum: - stdio type: string package: description: >- The package name in the runtime's ecosystem syntax; refused with mcp_server_package_invalid otherwise. type: string required: description: >- True: a task is not created until the connection its project's credential policy names can be used, and a turn that cannot reach the server fails, naming it. False, the Integrations tab's default: a task whose connection cannot be used starts without the server, and its agent is not given it. type: boolean runtime: description: >- npx (an npm package), uvx (a PyPI package's entry point) or python (python with a PyPI package, for python -m). Anything else is refused with mcp_server_runtime_invalid. type: string version: description: >- One exact release: full semver for npx, a PEP 440 version for uvx and python. Missing, latest, a range, a wildcard or a tag is refused with mcp_server_version_unpinned. type: string required: - kind - key - display_name - required - runtime - package - args - env type: object McpHTTPServer: additionalProperties: false properties: auth: enum: - none - static_secret - oauth type: string connection_kind: enum: - static_secret - oauth - github_user_credential - sentry_installation type: - string - 'null' created_at: format: date-time type: string default_credential_policy: enum: - creator - org type: - string - 'null' display_name: type: string enabled_by_default: type: boolean headers: additionalProperties: type: string type: object id: format: uuid type: string key: type: string kind: enum: - http type: string required: type: boolean secret_names: items: type: string type: array source: $ref: '#/components/schemas/McpServerSource' updated_at: format: date-time type: string url: type: string required: - kind - id - key - display_name - url - headers - auth - source - connection_kind - required - enabled_by_default - default_credential_policy - secret_names - created_at - updated_at type: object McpStdioServer: additionalProperties: false properties: args: items: type: string type: array auth: enum: - none - static_secret type: string connection_kind: enum: - static_secret type: - string - 'null' created_at: format: date-time type: string default_credential_policy: enum: - creator - org type: - string - 'null' display_name: type: string enabled_by_default: type: boolean env: additionalProperties: $ref: '#/components/schemas/McpStdioEnvValue' type: object id: format: uuid type: string key: type: string kind: enum: - stdio type: string package: type: string required: type: boolean runtime: enum: - npx - uvx - python type: string secret_names: items: type: string type: array source: $ref: '#/components/schemas/ManualMcpServerSource' updated_at: format: date-time type: string version: type: string required: - kind - id - key - display_name - runtime - package - version - args - env - auth - source - connection_kind - required - enabled_by_default - default_credential_policy - secret_names - created_at - updated_at type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object McpStdioEnvValue: discriminator: mapping: plain: '#/components/schemas/McpStdioPlainEnv' secret: '#/components/schemas/McpStdioSecretEnv' propertyName: kind oneOf: - $ref: '#/components/schemas/McpStdioPlainEnv' - $ref: '#/components/schemas/McpStdioSecretEnv' McpServerSource: discriminator: mapping: aether: '#/components/schemas/AetherMcpServerSource' directory: '#/components/schemas/DirectoryMcpServerSource' manual: '#/components/schemas/ManualMcpServerSource' plugin: '#/components/schemas/PluginMcpServerSource' propertyName: kind oneOf: - $ref: '#/components/schemas/ManualMcpServerSource' - $ref: '#/components/schemas/AetherMcpServerSource' - $ref: '#/components/schemas/PluginMcpServerSource' - $ref: '#/components/schemas/DirectoryMcpServerSource' ManualMcpServerSource: additionalProperties: false properties: kind: enum: - manual type: string required: - kind type: object McpStdioPlainEnv: additionalProperties: false properties: kind: enum: - plain type: string value: type: string required: - kind - value type: object McpStdioSecretEnv: additionalProperties: false properties: kind: enum: - secret type: string required: - kind type: object AetherMcpServerSource: additionalProperties: false properties: kind: enum: - aether type: string required: - kind type: object DirectoryMcpServerSource: additionalProperties: false properties: homepage: description: >- The integration's homepage, as Aether's integration directory names it. format: uri type: string kind: enum: - directory type: string required: - kind - homepage type: object PluginMcpServerSource: additionalProperties: false properties: kind: enum: - plugin type: string plugin_id: format: uuid type: string required: - kind - plugin_id type: object securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.