Skip to content

Configuration API Reference

Server specifications and configuration types.

StdioServerSpec

promptise.config.StdioServerSpec

Bases: _BaseServer

Specification for a local MCP server launched via stdio.

Attributes:

Name Type Description
command str

Executable to launch (e.g., "python").
args list[str]

Positional arguments for the process.
env dict[str, str]

Environment variables to set for the process.
cwd str | None

Optional working directory.
keep_alive bool

Whether the client should try to keep a persistent session.

HTTPServerSpec

promptise.config.HTTPServerSpec

Bases: _BaseServer

Specification for a remote MCP server reachable via HTTP/SSE.

Supports two authentication methods:

  1. Bearer token (JWT): pass a pre-issued token via bearer_token and it is automatically injected as Authorization: Bearer <token>.
  2. API key (simple secret): pass a pre-shared key via api_key and it is automatically injected as x-api-key: <key>.

Tokens should be obtained from your Identity Provider (Auth0, Keycloak, Okta, etc.) or from the MCP server's built-in token endpoint (for development/testing). The agent never generates tokens itself.

Attributes:

Name Type Description
url str

Full endpoint URL (e.g., http://127.0.0.1:8080/mcp).
transport Literal['http', 'streamable-http', 'sse']

"http", "streamable-http", or "sse".
headers dict[str, str]

Extra HTTP headers sent on every request.
auth str | None

Legacy auth hint.
bearer_token SecretStr | None

Pre-issued Bearer token. When set, an Authorization: Bearer <token> header is created automatically.
api_key SecretStr | None

Pre-shared API key. When set, an x-api-key header is created automatically. Use this for simple secret-based auth when JWT is overkill.

Example — Bearer token::

HTTPServerSpec(
    url="http://localhost:8080/mcp",
    bearer_token="eyJhbGciOiJIUzI1NiIs...",
)

Example — API key::

HTTPServerSpec(
    url="http://localhost:8080/mcp",
    api_key="my-secret-key",
)

Example — manual header::

HTTPServerSpec(
    url="http://localhost:8080/mcp",
    headers={"authorization": "Bearer <token>"},
)

ServerSpec

promptise.config.ServerSpec = StdioServerSpec | HTTPServerSpec module-attribute

Union of supported server specifications.

servers_to_mcp_config

promptise.config.servers_to_mcp_config(servers)

Convert programmatic server specs to a configuration dict.

Parameters:

Name Type Description Default
servers Mapping[str, ServerSpec]

Mapping of server name to specification.

 required

Returns:

Type Description
dict[str, dict[str, object]]

Dict with server configurations keyed by name.