Setup & Installation

Start the strata MCP server and configure your AI client to connect.

Prerequisites

strata CLI — installed and working
```
strata --version
```
Python 3.10+ — required by strata
MCP optional dependency — must be installed separately
Workspace — initialized with strata sln init

Step 1: Install the MCP Optional Dependency

The MCP server requires the mcp package, which is optional for strata to keep the base installation lightweight.

Option A: Install in Your Project Environment

If you’re developing a strata integration:

pip install xyz-strata[mcp]

This installs strata with the MCP extra, which includes the mcp package and FastMCP.

Option B: Install in a Global Environment

If you want to run the server independently:

# Create a virtual environment
python -m venv ~/.strata/mcp-env

# Activate it
source ~/.strata/mcp-env/bin/activate  # macOS/Linux
# or
~\.strata\mcp-env\Scripts\Activate.ps1  # Windows PowerShell

# Install strata with MCP
pip install xyz-strata[mcp]

Verify Installation

strata mcp serve --help

You should see the command help. If you get “command not found” or “unknown command”, the MCP package isn’t installed.

Step 2: Start the MCP Server

The server communicates via stdio (standard input/output), which is the standard MCP transport.

strata mcp serve

The server will:

Detect the workspace root (from CWD by walking up to find .strata/)
Load workspace configuration
Print a startup message to stderr
Begin listening for JSON-RPC requests on stdin

Important: The server runs indefinitely. It’s designed to be spawned by your MCP client (Claude, Copilot, etc.) and runs until the client closes stdin.

Specify Workspace Explicitly

If you want to run the server from a different directory:

cd /path/to/my/workspace && strata mcp serve

Or set the environment variable:

export STRATA_WORK_PATH=/path/to/my/workspace
strata mcp serve

Step 3: Configure Your MCP Client

Each AI platform configures MCP servers differently. Choose your platform below.

Claude (via Claude Desktop)

Create or edit ~/.claude/claude-config.json (macOS/Linux) or %APPDATA%\Roaming\Claude\claude-config.json (Windows)

Add the strata MCP server under mcpServers:

{
  "mcpServers": {
    "strata": {
      "command": "strata",
      "args": ["mcp", "serve"],
      "cwd": "/path/to/my/strata/workspace"
    }
  }
}

Restart Claude to load the new config.

Claude API / Python SDK

If using Claude Anthropic API with MCP:

import subprocess
from anthropic import Anthropic

client = Anthropic()

# Configure MCP server
strata_server = {
    "name": "strata",
    "uri": "stdio://path/to/my/workspace",
    "command": "strata",
    "args": ["mcp", "serve"],
}

# Start a conversation with strata tools available
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    system="You have access to strata infrastructure tools. Use them to validate, build, and preview deployments.",
    messages=[
        {
            "role": "user",
            "content": "Validate my deployment file and show me what would be built.",
        }
    ],
    tools=[...],  # Strata tools will be auto-discovered via MCP
)

GitHub Copilot

The VS Code extension currently uses the CLI directly (not MCP). MCP integration ideas are documented in Copilot Integration.

For Copilot extension development:

// .vscode/settings.json
{
  "codeium.enableCodeiumServer": true,
  "strata.mcp.server": "strata mcp serve",
  "strata.mcp.workspacePath": "${workspaceFolder}"
}

Generic MCP Client (Python / Node.js)

If building a custom MCP client:

# Python example
import subprocess
import json

# Start strata MCP server
server_process = subprocess.Popen(
    ["strata", "mcp", "serve"],
    cwd="/path/to/my/workspace",
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
)

# Send JSON-RPC requests to stdin
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "workspace_status",
        "arguments": {},
    },
}

server_process.stdin.write(json.dumps(request) + "\n")
server_process.stdin.flush()

# Read response from stdout
response = server_process.stdout.readline()
print(json.loads(response))

Step 4: Test the Connection

Once configured, test that your AI client can reach the strata server.

In Claude Desktop

Send a message:

“What tools do you have access to?”

Claude should mention strata tools like workspace_status, validate_file, build_plan, etc.

Programmatically

# Send a test request via stdin
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_schemas","arguments":{}}}' | strata mcp serve

Troubleshooting

Error: “command not found: strata”

Solution: Ensure strata is installed and in your $PATH:

which strata
strata --version

Error: “The `mcp` package is required”

Solution: Install the MCP optional dependency:

pip install xyz-strata[mcp]

Error: “Not inside a strata workspace”

Solution: The server can’t find .strata/. Either:

Run the server from inside a workspace directory
Set STRATA_WORK_PATH environment variable
Specify cwd in your MCP client configuration

cd /path/to/workspace && strata mcp serve
# or
export STRATA_WORK_PATH=/path/to/workspace && strata mcp serve

Server starts but client can’t connect

Solution: Verify stdio transport is working:

echo '{}' | strata mcp serve 2>&1 | head -20

You should see a response (even if it’s an error). If you see nothing, check that:

The MCP package is installed
The workspace path is valid
Firewall/antivirus isn’t blocking subprocess communication

Environment Variables

Configure server behavior via environment variables:

Variable	Purpose	Example
`STRATA_WORK_PATH`	Workspace root (overrides CWD walk)	`/path/to/workspace`
`STRATA_VERBOSE`	Enable verbose logging	`1`
`STRATA_QUIET`	Suppress non-error output	`1`
`STRATA_OUTPUT`	Output format	`json` or `text`

Example:

export STRATA_WORK_PATH=/my/workspace
export STRATA_VERBOSE=1
strata mcp serve

Next Steps

Configure Claude for a full walkthrough
Review Security before using in production
Explore Tools to see what’s available