Skip to main content

Run the API server

ToolHive includes a built-in API server that provides a RESTful interface for interacting with MCP servers. The API server is useful for integrating ToolHive with other applications or automating tasks.

note

The API server is designed for local automation and UI development. By default, it binds to localhost (127.0.0.1) and starts without authentication, so any process on the same machine can call it.

If you expose the API server beyond localhost, enable OIDC authentication so that ToolHive requires a valid token on every request. See Authenticate API requests with OIDC below.

For multi-user, production environments, consider the ToolHive Kubernetes Operator, which provides a more robust and secure way to manage ToolHive instances.

Start the API server​

To start the API server, use the following command:

thv serve

This starts the API server on localhost (127.0.0.1) using the default port 8080.

Test the API server using curl or a web browser:

curl http://localhost:8080/api/v1beta/status

You should see a JSON response with the current ToolHive version.

Custom networking​

By default, the API server listens on localhost (127.0.0.1) port 8080.

You can specify a different port using the --port option:

thv serve --port <PORT_NUMBER>

If you're running the API server on a remote host, specify the hostname or IP address to bind to using the --host option:

thv serve --host <HOSTNAME_OR_IP>

UNIX socket and Windows named-pipe support​

The API server can also be exposed via a UNIX socket or Windows named pipe instead of a TCP port. Use the --socket option to specify the address.

On macOS and Linux, pass a filesystem path for a UNIX domain socket:

thv serve --socket /tmp/toolhive.sock

On Windows, pass a named-pipe path:

thv serve --socket \\.\pipe\thv-api

ToolHive auto-detects the address type from its prefix: addresses starting with \\.\pipe\ open as a Windows named pipe; anything else opens as a UNIX domain socket. Named-pipe addresses are rejected on non-Windows platforms.

When using --socket, the argument overrides the host:port address configuration.

Authenticate API requests with OIDC​

By default, the API server accepts requests without authentication. This is fine when it's bound to localhost, but if you bind it to a routable address with --host, anyone who can reach that address can manage your MCP servers. To protect the API server, enable OpenID Connect (OIDC) authentication so that ToolHive validates a bearer token on every request.

ToolHive connects to your existing identity provider (such as Google, Okta, Microsoft Entra ID, Auth0, or Kubernetes) and verifies that incoming tokens were issued by that provider. ToolHive never sees your password, only the tokens your identity provider issues.

To enable OIDC validation, provide at least one of --oidc-issuer, --oidc-jwks-url, or --oidc-introspection-url. If none of these are set, the API server starts unauthenticated.

The following options configure OIDC validation:

OptionDescription
--oidc-issuerOIDC issuer URL, for example https://accounts.google.com. ToolHive discovers the JWKS URL from it.
--oidc-audienceExpected audience (aud claim) for the token. Tokens issued for a different audience are rejected.
--oidc-jwks-urlURL to fetch the JSON Web Key Set (JWKS) from. Optional when --oidc-issuer is set and supports discovery.
--oidc-introspection-urlToken introspection endpoint (RFC 7662) for validating opaque tokens.
--oidc-client-idOIDC client ID.
--oidc-client-secretOIDC client secret. Optional, used for token introspection.
--oidc-scopesOAuth scopes to advertise in the protected resource metadata endpoint (RFC 9728). Defaults to openid.

When you set --oidc-issuer without --oidc-jwks-url, ToolHive discovers the JWKS URL from the issuer's OIDC discovery document on the first request, so the server can start before your identity provider is reachable.

The following example starts the API server bound to a routable address and validates signed JWT tokens against an issuer:

thv serve \
  --host 0.0.0.0 \
  --port 8080 \
  --oidc-issuer https://your-oidc-issuer.com \
  --oidc-audience toolhive-api

You only need --oidc-client-id and --oidc-client-secret when validating opaque tokens through an introspection endpoint.

Clients must then send a valid token in the Authorization header:

curl -H "Authorization: Bearer <TOKEN>" \
  http://your-host:8080/api/v1beta/version

For background on how ToolHive uses OIDC, JWT validation, and authorization policies, see the authentication and authorization framework.

API documentation​

See the ToolHive API documentation for details on available endpoints, request and response formats.

You can also run a local instance of the API documentation using the --openapi option:

thv serve --openapi

Open a browser to http://localhost:8080/api/doc to view the API documentation. The OpenAPI specification is also available at http://localhost:8080/api/openapi.json.

Next steps​