Connect MCP Servers

Connect Claude Code, ChatGPT, and other AI clients to your systemprompt MCP servers. OAuth-secured tool access with full audit trail.

Last updated:

MCP (Model Context Protocol) lets AI clients like Claude Code and ChatGPT use tools from your systemprompt instance. This guide shows you how to connect them.

What is MCP?

MCP is a protocol that allows AI models to discover and invoke external tools. Your systemprompt template hosts MCP servers that expose tools—the AI client connects, discovers available tools, and calls them during conversations.

┌─────────────────┐     MCP Protocol      ┌─────────────────┐
│   Claude Code   │ ◄──────────────────► │  systemprompt   │
│   (MCP Client)  │                       │  (MCP Server)   │
└─────────────────┘                       └─────────────────┘

Prerequisites

Running systemprompt instance
For production: deployed to cloud with SSL (see Deploy as a Website)

Check Available MCP Servers

List your MCP servers:

# List configured servers
systemprompt plugins mcp list

# Show running servers with status
systemprompt plugins mcp status

# List tools available from a server
systemprompt plugins mcp tools systemprompt

Default MCP servers:

Server	Port	Description
`systemprompt`	5010	CLI command execution
`soul`	5020	AI-powered content tools
`content-manager`	5040	Content management tools

Connect Claude Code

Claude Code (the CLI tool) and Claude Desktop both support MCP servers.

Local Development

Edit your Claude Code configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/claude/claude_desktop_config.json

Add your MCP server:

{
  "mcpServers": {
    "systemprompt": {
      "url": "http://localhost:8080/api/v1/mcp/systemprompt/mcp",
      "transport": "streamable-http"
    }
  }
}

Restart Claude Code after editing the configuration.

Production (with OAuth)

For production deployments with authentication:

{
  "mcpServers": {
    "systemprompt": {
      "url": "https://your-tenant.systemprompt.io/api/v1/mcp/systemprompt/mcp",
      "transport": "streamable-http",
      "oauth": {
        "clientId": "claude-desktop",
        "authorizationUrl": "https://your-tenant.systemprompt.io/api/v1/core/oauth/authorize",
        "tokenUrl": "https://your-tenant.systemprompt.io/api/v1/core/oauth/token",
        "scopes": ["admin"]
      }
    }
  }
}

When you first use a tool, Claude will prompt you to authenticate via your browser.

Connect ChatGPT

ChatGPT supports MCP through plugins and custom GPTs.

Option 1: Custom GPT with Actions

Go to ChatGPT > Explore GPTs > Create
In Configure, add an Action
Set the server URL:

https://your-tenant.systemprompt.io/api/v1/mcp/systemprompt/mcp

Configure authentication:
- Type: OAuth 2.0
- Authorization URL: https://your-tenant.systemprompt.io/api/v1/core/oauth/authorize
- Token URL: https://your-tenant.systemprompt.io/api/v1/core/oauth/token
- Scopes: admin

Option 2: MCP Client Plugin

If ChatGPT has an MCP client plugin available:

Go to ChatGPT Settings > Beta features > Plugins
Install the MCP Client plugin
Configure the endpoint URL and OAuth credentials

Test MCP Connection

Test via CLI

# Validate MCP server connection
systemprompt plugins mcp validate systemprompt

# Call a tool directly
systemprompt plugins mcp call systemprompt list_playbooks

# List all available tools
systemprompt plugins mcp tools systemprompt

Test via HTTP

# List available tools
curl http://localhost:8080/api/v1/mcp/systemprompt/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

# Call a specific tool
curl http://localhost:8080/api/v1/mcp/systemprompt/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_playbooks",
      "arguments": {}
    },
    "id": 1
  }'

OAuth Authentication

MCP servers support OAuth 2.0 for secure access control.

Server Configuration

Configure OAuth in your MCP server config (e.g., services/mcp/systemprompt.yaml):

mcp_servers:
  systemprompt:
    binary: "systemprompt-mcp-agent"
    package: "systemprompt"
    port: 5010
    endpoint: "http://localhost:8080/api/v1/mcp/systemprompt/mcp"
    enabled: true

    oauth:
      required: true
      scopes: ["admin"]
      audience: "mcp"

Scope Reference

Scope	Access Level
`anonymous`	Public tools only
`user`	User-level tools
`admin`	All tools including admin
`tools:read`	Read-only tool access
`tools:write`	Tool execution

View Audit Logs

All MCP tool calls are logged for security and debugging:

# View MCP server logs
systemprompt plugins mcp logs systemprompt

# View recent tool calls
systemprompt infra logs view --level info --since 1h | grep "mcp"

# Audit specific request
systemprompt infra logs request list --limit 10
systemprompt infra logs audit <request-id> --full

Each log entry includes:

Timestamp
Tool name and arguments
User/client identity
Response status
Execution duration

Add Custom MCP Server

Create a new MCP server to expose your own tools:

1. Create Configuration

# services/mcp/my-tools.yaml
mcp_servers:
  my-tools:
    binary: "my-tools-mcp"
    package: "my-tools"
    port: 5050
    endpoint: "http://localhost:8080/api/v1/mcp/my-tools/mcp"
    enabled: true
    display_in_web: true
    description: "My custom tools"

    oauth:
      required: false

2. Build the Server

See the MCP Extensions documentation for building Rust MCP servers.

3. Sync and Restart

systemprompt cloud sync local mcp --direction to-db -y
systemprompt infra services restart --all

Troubleshooting

"Server not found"

# Check server is configured
systemprompt plugins mcp list

# Check server is running
systemprompt plugins mcp status

# Restart MCP servers
systemprompt infra services restart mcp

"Tool execution failed"

# Check server logs
systemprompt plugins mcp logs systemprompt

# Check for errors in log files
grep -i "error\|failed" logs/mcp-systemprompt.log | tail -30

"Authentication required"

Ensure your MCP client is configured with OAuth credentials matching your server configuration. For local development, you can disable OAuth:

oauth:
  required: false

"Connection refused"

For local development, ensure services are running:

just start
# or
systemprompt infra services start --all

For production, verify your deployment is healthy:

systemprompt cloud status

Security Best Practices

Always use OAuth in production - Never expose unauthenticated MCP servers publicly
Use minimal scopes - Only grant the scopes each client needs
Monitor audit logs - Review tool calls regularly for suspicious activity
Rotate credentials - Periodically refresh OAuth client secrets
Restrict tools - Only expose the tools your clients need

# Restrict which tools are exposed
mcp_servers:
  systemprompt:
    tools:
      allowed:
        - list_playbooks
        - show_playbook
      denied:
        - delete_*
        - admin_*

Next Steps

MCP Configuration - Deep dive into MCP server configuration
Build MCP Server - Create custom tool servers
Deploy as a Website - Production deployment
Talk to Your Agents - Agent communication