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. Values of credential headers (Authorization, Cookie, x-api-key, names containing token, secret, ...) are sent as given but shown as ********** in repr() and in model_dump(mode="json") (a ${VAR} resolved from a manifest never shows up in a dump or a log line). model_dump() in Python mode keeps them, so a spec can be rebuilt from it.
auth	str | None	Deprecated and ignored — it was never sent to the server. Setting it emits a FutureWarning; use bearer_token or api_key.
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.
forward_caller_token	bool | None	Whether an invocation's caller token reaches this server. When it does and the invocation carries a :class:~promptise.CallerContext with a bearer_token, this server's tools are called with Authorization: Bearer <caller token> over a session opened for that caller, so the server sees the user, not whoever built the agent. The caller's token replaces bearer_token (and any Authorization header), which, like the agent identity, is still used for tool discovery and for calls without a caller token. None (default): forward, unless the server is configured with an API key (api_key or an x-api-key header). An API key is the server's explicit credential and wins: the caller's bearer would be sent next to it, and a gate that checks the bearer first (a Promptise server does) rejects the call with 401. True: always forward, also to an API-key server; the key is still sent, so the server receives both and decides which one counts (a Promptise server checks the bearer first). False: never forward; use it for a third-party server that must not receive your users' tokens, or one that should always see the agent's own credential. See :attr:forwards_caller_token for the resolved value.

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>"},
)

forwards_caller_token property

Whether tool calls send the invoking caller's bearer token here.

forward_caller_token when it is set; otherwise True unless the server has an API key (:attr:has_api_key), which then wins over the caller's token.

has_api_key property

Whether an API key is configured (api_key or an x-api-key header).

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.