Getting Started - MCP Server¶

URSA can run as a Model Context Protocol server so other MCP-compatible clients or agent frameworks can use URSA capabilities.

Note

This guide assumes basic familiarity with the Model Context Protocol.

Prerequisites¶

URSA is installed.
You have a model configuration file.
You understand the session-isolation warning below.

Session isolation

The URSA MCP server does not isolate sessions from one another. Do not run it as a shared multi-user service unless you have added appropriate isolation and access controls.

Configure the served URSA instance¶

Create config.yaml:

llm_model:
  model: openai:gpt-5.4
  api_key:
    env: OPENAI_API_KEY
workspace: ./ursa-mcp-workspace

stdio transport¶

Use stdio when an MCP client launches URSA directly:

ursa --config config.yaml mcp-server --transport stdio

You can inspect it with MCP Inspector:

npx @modelcontextprotocol/inspector \
  uv run ursa --config config.yaml mcp-server --transport stdio

Streamable HTTP transport¶

Use streamable HTTP when you want to run a local server and connect to it separately:

ursa --config config.yaml mcp-server \
  --transport streamable-http \
  --host localhost \
  --port 8000

Connect clients to:

http://localhost:8000/mcp

Inspect the running server:

npx @modelcontextprotocol/inspector \
  --transport http \
  --server-url http://localhost:8000/mcp

See all MCP server options¶

ursa mcp-server --help

Current options include:

--transport {stdio,streamable-http}
--host HOST
--port PORT
--log_level {debug,info,notice,warning,error,critical}