server-specs

Server Configuration

Configure how agents connect to MCP servers using StdioServerSpec for local servers and HTTPServerSpec for remote ones.

Quick Example

=== "Stdio"

```python
from promptise.config import StdioServerSpec

servers = {
    "math": StdioServerSpec(
        command="python",
        args=["-m", "math_server"],
    ),
}
```

=== "HTTP"

```python
from promptise.config import HTTPServerSpec

servers = {
    "api": HTTPServerSpec(
        url="http://localhost:8000/mcp",
        bearer_token="eyJhbGciOiJIUzI1NiIs...",
    ),
}
```

Concepts

Every Promptise agent receives a servers dict that maps a human-readable name to a server specification. The agent connects to each server at startup, discovers its tools, and makes them available to the LLM.

There are two spec types:

• StdioServerSpec -- launches a local process and communicates over stdin/stdout. Best for local development and bundled servers.
• HTTPServerSpec -- connects to a remote server over HTTP, Streamable HTTP, or SSE. Best for production deployments and shared services.

Both are Pydantic models with strict validation (extra="forbid"), so typos in field names are caught immediately.

StdioServerSpec

Use StdioServerSpec when the MCP server is a local process that the agent should launch and manage.

from promptise.config import StdioServerSpec

spec = StdioServerSpec(
    command="python",
    args=["-m", "mypackage.server", "--port", "0"],
    env={"API_KEY": "sk-..."},
    cwd="/path/to/project",
    keep_alive=True,
)

Fields

Field	Type	Default	Description
command	str	required	Executable to launch (e.g. "python", "node", "npx").
args	list[str]	[]	Positional arguments for the process.
env	dict[str, str]	{}	Environment variables set for the child process.
cwd	str | None	None	Working directory for the process.
keep_alive	bool	True	Whether the client should maintain a persistent session.