---
title: "Create tool server"
method: POST
path: "/v2/tool_servers"
tags: ["Tool Servers"]
---

# Create tool server

`POST /v2/tool_servers`

Creates a tool server that exposes tools for use by agents.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- CreateToolServerRequest — Request object for creating a new tool server.
  - `name` string, required — The human-readable name of a tool server.
  - `type` 'mcp', required — The type of tool server.
  - `description` string — A detailed description of what this tool server does.
  - `uri` string, uri, required — The URI of the tool server.
  - `headers` object — Optional HTTP headers to include when connecting to the server.
  - `transport` 'sse' | 'streamable-http', required — Transport protocol for MCP server connections. Both use Server-Sent Events (SSE). - `sse`: Legacy format (https://modelcontextprotocol.io/specification/2024-11-05/basic/transports) - `streamable-http`: New format (https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)
  - `auth` union — Authentication configuration for connecting to a remote service.
    - object — Bearer token authentication
      - `type` string, required — Must be "bearer" for bearer token auth
      - `token` string, required — The bearer token to use for authentication
    - object — Custom header-based authentication
      - `type` string, required — Must be "header" for header-based auth
      - `header` string, required — The header name to use (e.g. x-api-key)
      - `value` string, required — The header value to use
    - object — OAuth 2.0 client credentials authentication. The platform acquires an access token from the token endpoint before connecting to the remote service.
      - `type` string, required — Must be "oauth_client_credentials" for OAuth client credentials auth.
      - `client_id` string, required — The OAuth2 client ID.
      - `client_secret` string, required — The OAuth2 client secret.
      - `token_endpoint` string, uri, required — The OAuth2 token endpoint URL where the platform exchanges credentials for an access token.
      - `scopes` string[] — OAuth2 scopes to request when acquiring the access token.
      - `audience` string — Sent as the OAuth `audience` form parameter so the identity provider mints a token whose `aud` claim targets this value. Required by some identity providers, such as Ory Hydra and Auth0.
      - `client_auth_method` 'client_secret_basic' | 'client_secret_post' — How the platform presents the client ID and secret to the token endpoint, named after the OAuth `token_endpoint_auth_method` registry. `client_secret_basic` sends them in an HTTP Basic `Authorization` header. `client_secret_post` sends them as `client_id` and `client_secret` form fields in the request body. Set this to the method the client application is registered with at the identity provider.
  - `enabled` boolean — Whether the tool server is currently enabled and available for use.
  - `metadata` object — Arbitrary metadata associated with the tool server.

## Response `201`

The created tool server details.

- ToolServer — A tool server that exposes tools for use by agents.
  - `id` string — Unique identifier for a tool server.
  - `name` string, required — The human-readable name of a tool server.
  - `type` 'mcp', required — The type of tool server.
  - `description` string — A detailed description of what this tool server does.
  - `uri` string, uri, required — The URI of the server.
  - `headers` object — Optional HTTP headers to include when connecting to the server.
  - `transport` 'sse' | 'streamable-http', required — Transport protocol for MCP server connections. Both use Server-Sent Events (SSE). - `sse`: Legacy format (https://modelcontextprotocol.io/specification/2024-11-05/basic/transports) - `streamable-http`: New format (https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)
  - `enabled` boolean, required — Whether the tool server is currently enabled and available for use.
  - `metadata` object — Arbitrary metadata associated with the tool server.
  - `created_at` string, date-time — Timestamp when the tool server was created.
  - `updated_at` string, date-time — Timestamp when the tool server was last updated.

## Other responses

- `400` — Invalid request body.
- `403` — Permissions do not allow creating tool servers.

## Changes

- **2026-09-23** `3f4075adad3d` — 2 info
  - added the new optional request property `auth/oneOf[#/components/schemas/OAuthClientCredentialsAuth]/audience`
  - added the new optional request property `auth/oneOf[#/components/schemas/OAuthClientCredentialsAuth]/client_auth_method`

[Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/tool_servers/post.md)

---

[API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/revisions/4557c44ba062?raw)