Quick Start

Get up and running with SystemPrompt in minutes

On this page

Get SystemPrompt running in minutes. This guide assumes you've completed installation.

Using the Template

The fastest way to start is with the official template:

# Clone the template
git clone --recursive https://github.com/systempromptio/systemprompt-template my-project
cd my-project

# Start the database
just db-up

# Run setup (migrations + content sync)
just quickstart

# Start the server
just start

Your SystemPrompt instance is now running at http://localhost:3000.

Project Structure

The template includes:

my-project/
├── core/                    # systemprompt-core (git submodule, read-only)
├── extensions/              # Your Rust extensions
│   ├── blog/               # Blog extension (example)
│   └── mcp/                # MCP servers
├── services/               # Configuration (YAML/Markdown only)
│   ├── agents/             # Agent definitions
│   ├── config/             # Service configuration
│   ├── content/            # Blog and docs content
│   ├── mcp/                # MCP server definitions
│   ├── skills/             # Agent skill definitions
│   ├── scheduler/          # Background jobs
│   └── web/                # Theme and branding
└── src/                    # Application entry point

Define Your First Agent

Create an agent definition in services/agents/:

# services/agents/assistant.yaml
name: assistant
description: A helpful AI assistant

a2a_card:
  protocol_version: "1.0"
  display_name: "Assistant"
  capabilities:
    text: true
    images: false
  transport:
    type: http
    endpoint: "/api/v1/agents/assistant"
  security_schemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "/oauth/token"
          scopes:
            chat: "Send messages to the agent"

skills:
  - general_assistance
  - content_writing

system_prompt: |
  You are a helpful AI assistant. You help users with their questions
  and tasks. Be concise and accurate.

security:
  oauth2:
    scopes: ["chat"]

Sync the agent to the database:

systemprompt cloud sync local agents --direction to-db -y

Create an MCP Server

Define an MCP server in services/mcp/:

# services/mcp/tools.yaml
name: tools
description: Utility tools for the assistant
binary: mcp-tools

transport:
  type: streamable-http
  endpoint: "/api/v1/mcp/tools/mcp"

oauth:
  required: true
  scopes: ["tools:read", "tools:write"]

tools:
  - name: get_weather
    description: Get current weather for a location
  - name: search_web
    description: Search the web for information

Build and register the MCP server:

just build-mcp
systemprompt cloud sync local mcp --direction to-db -y

Test Your Setup

Check the Agent Registry

# List all agents
systemprompt admin agents list

# View agent details
systemprompt admin agents show assistant

Send a Message

# Send a message to your agent
systemprompt admin agents message assistant "Hello, how are you?"

Check MCP Registry

# List MCP servers
curl http://localhost:3000/api/v1/mcp/registry

Discovery Endpoints

Your agent is discoverable at:

Endpoint Description
/.well-known/agent-card.json Default agent card
/.well-known/agent-cards List all agents
/.well-known/agent-cards/assistant Specific agent card
/api/v1/agents/registry Full registry with status
/api/v1/mcp/registry All MCP servers

Connect Claude Desktop

Add your MCP server to Claude Desktop:

// claude_desktop_config.json
{
  "mcpServers": {
    "tools": {
      "url": "http://localhost:3000/api/v1/mcp/tools/mcp",
      "transport": "streamable-http"
    }
  }
}

Common Commands

# Development
just build              # Build all crates
just start              # Start the server
just watch              # Start with auto-reload

# Database
just migrate            # Run migrations
just db-up              # Start PostgreSQL
just db-down            # Stop PostgreSQL

# Content
just sync-local         # Sync all content to database
just build-mcp          # Build MCP servers

# Deployment
systemprompt cloud deploy --profile production

Next Steps