Peta

https://docs.peta.io/
Admin
Peta is a control plane for Model Context Protocol (MCP) that manages MCP server lifecycle, enforces...
Tokens:41,982
Snippets:472
Trust Score:5.4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Peta Auth Service Installation Prompt

Source: https://docs.peta.io/#getting-started

This is an example of the interactive prompt encountered during Peta Core deployment, asking whether to install and start the peta-auth service. Selecting 'Y' enables Peta's built-in OAuth integrations, while 'n' requires a Bring Your Own Cloud (BYOC) OAuth app registration.

```text
Install and start peta-auth service? [Y/n]:
```

--------------------------------

### Peta Docker Compose Management Commands (Windows)

Source: https://docs.peta.io/#windows-deployment

A collection of common Docker Compose commands for managing Peta services, including starting, stopping, restarting, viewing logs, pulling images, and managing volumes.

```bash
# Navigate to deployment directory
cd .\peta-deployment

# View status
docker compose ps

# View logs (add service name to focus)
docker compose logs -f

# Pull Docker images
docker compose pull

# Starting services
docker compose up -d

# Restart services
docker compose restart

# Stop services
docker compose down

# Stop and remove containers, networks, volumes (⚠️ destructive)
docker compose down -v

# Edit configuration
notepad .env
```

--------------------------------

### Download and Run Peta Windows Deployment Script

Source: https://docs.peta.io/#windows-deployment

Downloads the Peta deployment script for Windows using Invoke-WebRequest and then executes the script to automate the installation process.

```powershell
# Download Windows deployment script
Invoke-WebRequest -Uri https://files.peta.io/installation/deploy-peta-win.ps1 -OutFile deploy-peta-win.ps1

# Run automated deployment
.\deploy-peta-win.ps1
```

--------------------------------

### Handle Port Conflicts

Source: https://docs.peta.io/#macos-deployment

Example output demonstrating the automated port conflict detection and interactive resolution mechanism used during the deployment process.

```text
[WARN] Port 3002 is already in use
[INFO] Purpose: peta-core service startup port
Please enter a new port number (1024-65535) or 'q' to quit: 3003
[SUCCESS] Port 3003 is available
```

--------------------------------

### Deploy Peta on macOS

Source: https://docs.peta.io/#macos-deployment

Downloads and executes the official Peta deployment script for macOS. This script handles the interactive setup of Core and Console services.

```bash
curl -O https://files.peta.io/installation/deploy-peta-mac.sh
chmod +x deploy-peta-mac.sh
./deploy-peta-mac.sh
```

--------------------------------

### Interpreting Peta Log Sequences

Source: https://docs.peta.io/#log-analysis

Example log outputs demonstrating typical healthy startup sequences versus actionable error sequences. Developers should use these patterns to distinguish between routine lifecycle events and integration-specific failures.

```text
# Healthy Startup Sequence
[INFO] STARTUP: Peta Core booting on :3002
[INFO] CONFIG: Loaded runtime configuration
[INFO] SUCCESS: PostgreSQL connection established
[INFO] SUCCESS: MCP server 'github-mcp' Connected
[INFO] SUCCESS: Health checks passed

# Error Sequence
[WARN] RETRY: MCP call timeout for server 'notion-mcp' (attempt 1/3)
[WARN] RETRY: MCP call timeout for server 'notion-mcp' (attempt 2/3)
[ERROR] TIMEOUT: Tool invocation failed after retries
[ERROR] AUTH: Upstream returned 401 for 'notion-mcp'
[INFO] Auto-recovery scheduled reconnect
```

--------------------------------

### Configure Lazy Loading

Source: https://docs.peta.io/#macos-deployment

Environment variable configuration to enable lazy loading for MCP servers, reducing resource consumption by starting servers only upon request.

```bash
LAZY_START_ENABLED=true
```

--------------------------------

### JSON Configuration for MCP Servers in Claude Code

Source: https://docs.peta.io/#mcp-client-claude-code

This JSON configuration example shows how to add MCP servers to your Claude Code setup. It includes the server type, URL, and authorization headers. This configuration is pasted into the Claude Code configuration file.

```json
{
  "mcpServers": {
    "My MCP Server": {
      "type": "http",
      "url": "https://17bfmjzc74.p-mcp.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}
```

--------------------------------

### Enable PowerShell Script Execution (Windows)

Source: https://docs.peta.io/#windows-deployment

Configures the PowerShell execution policy to allow locally created scripts to run without signing. This is a one-time setup required for running downloaded scripts and only affects the current user.

```powershell
# Enable script execution (one-time setup, run as Administrator)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

--------------------------------

### REST API Advanced Configuration Options

Source: https://docs.peta.io/#tool-restful-api

Examples of advanced configuration settings for RESTful API integrations, including rate limiting, retry logic, request timeouts, and default headers.

```json
{
  "rate_limit": {
    "requests_per_second": 10,
    "requests_per_day": 1000
  }
}
```

```json
{
  "retry": {
    "max_attempts": 3,
    "backoff": "exponential"
  }
}
```

```json
{
  "timeout": {
    "connect": 5000,
    "read": 30000
  }
}
```

```json
{
  "default_headers": {
    "User-Agent": "Peta/1.0",
    "Accept": "application/json"
  }
}
```

--------------------------------

### Initialize Proxy and Authenticate

Source: https://docs.peta.io/#console-api

Initializes the proxy service and generates an owner access token. This is a public endpoint that requires a master password to establish the initial session.

```HTTP
POST /api/external/auth/init HTTP/1.1
Content-Type: application/json

{
  "masterPwd": "your_master_password"
}
```

--------------------------------

### Manage Existing Deployments

Source: https://docs.peta.io/#macos-deployment

Commands to restart existing services or perform a full cleanup and redeployment of the Peta platform.

```bash
# Start Existing Services
cd peta-deployment && docker compose up -d

# Complete Redeployment
cd peta-deployment && docker compose down -v
cd .. && rm -rf peta-deployment
./deploy-peta-mac.sh
```

--------------------------------

### GET /mcp

Source: https://docs.peta.io/#mcp-client-integration

The primary endpoint for establishing a connection between an MCP client and the Peta Core server.

```APIDOC
## GET /mcp

### Description
This endpoint serves as the entry point for MCP clients to connect to the Peta Core service. It requires authentication via a Bearer token.

### Method
GET

### Endpoint
https://your-host:3002/mcp

### Parameters
#### Headers
- **Authorization** (string) - Required - The Bearer token in the format "Bearer <SERVICE_TOKEN>"

### Request Example
GET /mcp HTTP/1.1
Host: your-host:3002
Authorization: Bearer <SERVICE_TOKEN>

### Response
#### Success Response (200)
- **status** (string) - Connection established successfully

#### Response Example
{
  "status": "connected",
  "message": "MCP server handshake successful"
}
```

--------------------------------

### Batch Update Token Namespaces (API)

Source: https://docs.peta.io/#namespace-management

Provides an example of how to update the namespaces for multiple tokens simultaneously using their tokenIds. This is efficient for bulk reorganizations.

```json
POST /api/external/tokens/batch-update
{
  "tokenIds": ["tok_1", "tok_2"],
  "namespace": "production"
}
```

--------------------------------

### POST /tools/basic-mcp

Source: https://docs.peta.io/#console-api

Create a new basic MCP tool using a predefined template.

```APIDOC
## POST /tools/basic-mcp

### Description
Creates a basic MCP tool instance based on a provided template ID and configuration.

### Method
POST

### Endpoint
/tools/basic-mcp

### Request Body
- **toolTmplId** (string) - Required - The ID of the template to use.
- **mcpJsonConf** (object) - Required - Configuration object for the template.
- **allowUserInput** (boolean) - Optional - Default: false.
- **lazyStartEnabled** (boolean) - Optional - Default: true.
- **publicAccess** (boolean) - Optional - Default: false.

### Response
#### Success Response (200)
- **toolId** (string) - The ID of the newly created tool.

### Response Example
{
  "toolId": "basic-mcp-999"
}
```

--------------------------------

### Download Peta Deployment Script for Windows

Source: https://docs.peta.io/#quick-start

Downloads the Peta deployment script for Windows using PowerShell. This script is for native Windows deployment and requires PowerShell to be run as Administrator with a specific execution policy.

```powershell
Invoke-WebRequest -Uri https://files.peta.io/installation/deploy-peta-win.ps1 -OutFile deploy-peta-win.ps1
```

--------------------------------

### Download Peta Deployment Script for Windows

Source: https://docs.peta.io/#getting-started

Downloads the Peta deployment script for Windows using PowerShell. This script is for native Windows deployment and requires PowerShell to be run as Administrator with a specific execution policy set.

```powershell
Invoke-WebRequest -Uri https://files.peta.io/installation/deploy-peta-win.ps1 -OutFile deploy-peta-win.ps1
# Run PowerShell as Administrator and set execution policy: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

--------------------------------

### POST /tools

Source: https://docs.peta.io/#console-api

List all available tools with optional filtering.

```APIDOC
## POST /tools

### Description
Retrieves a list of all tools managed by the owner. Supports filtering by enabled status.

### Method
POST

### Endpoint
/tools

### Request Body
- **enabled** (boolean) - Optional - Filter tools by their enabled status.

### Response
#### Success Response (200)
- **tools** (array) - List of tool objects.

### Response Example
{
  "tools": [{"id": "tool-123", "name": "Example Tool", "enabled": true}]
}
```

--------------------------------

### Restart Peta Core Service

Source: https://docs.peta.io/#integration-errors

Use this command to force a restart of the Peta core service. This is useful for refreshing cached schemas or recovering from integration connection failures.

```bash
docker compose restart peta-core
```

--------------------------------

### Peta PowerShell Port Detection Function

Source: https://docs.peta.io/#windows-deployment

A PowerShell function that checks if a specific TCP port is currently being listened on by any process. It returns true if the port is free and false otherwise.

```powershell
# PowerShell port detection function
function Test-Port {
  $connection = Get-NetTCPConnection -LocalPort $Port \
    -State Listen -ErrorAction SilentlyContinue
  return $null -eq $connection
}
```

--------------------------------

### Authentication API

Source: https://docs.peta.io/#console-api

Endpoints for initializing the proxy and obtaining owner access tokens.

```APIDOC
## POST /api/external/auth/init

### Description
Initialize proxy and create owner token. This is a public endpoint.

### Method
POST

### Endpoint
/api/external/auth/init

### Parameters
#### Request Body
- **masterPwd** (string) - Required - The master password for proxy initialization.

### Request Example
```json
{
  "masterPwd": "your_master_password"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the owner access token and other relevant information.
  - **ownerAccessToken** (string) - The generated owner access token.

#### Response Example
```json
{
  "success": true,
  "data": {
    "ownerAccessToken": "<owner_access_token>"
  }
}
```

#### Error Response (e.g., 400, 401, 500)
- **success** (boolean) - Indicates if the operation was successful (false for errors).
- **error** (object) - Contains error details.
  - **code** (string) - The error code.
  - **message** (string) - A description of the error.

#### Error Response Example
```json
{
  "success": false,
  "error": {
    "code": "E1001",
    "message": "Invalid master password"
  }
}
```
```

--------------------------------

### Create Token with Namespace (API)

Source: https://docs.peta.io/#namespace-management

Shows how to create a new token and assign it to a specific namespace. This allows for immediate organization of newly created tokens.

```json
POST /api/external/tokens/create
{
  "tokens": [{
    "name": "Production API",
    "role": 3,
    "namespace": "production"
  }]
}
```

--------------------------------

### Run Peta Deployment Script

Source: https://docs.peta.io/#getting-started

Executes the downloaded Peta deployment script for various operating systems. After execution, the script will guide the user through interactive prompts for deployment configuration.

```shell
# macOS
./deploy-peta-mac.sh

# Windows
.\deploy-peta-win.ps1

# Linux
./deploy-peta-linux.sh
```

--------------------------------

### POST /ip-whitelist/add

Source: https://docs.peta.io/#console-api

Add IP addresses to the whitelist.

```APIDOC
## POST /ip-whitelist/add

### Description
Adds a list of IP addresses to the current access whitelist.

### Method
POST

### Endpoint
/ip-whitelist/add

### Request Body
- **ips** (string[]) - Required - Array of IP addresses to whitelist.

### Response
#### Success Response (200)
- **status** (string) - Confirmation message.

### Response Example
{
  "status": "success"
}
```

--------------------------------

### Inspect Peta Core Logs

Source: https://docs.peta.io/#integration-errors

Use this command to monitor real-time logs for the Peta core service. This is essential for identifying handshake, timeout, or authentication errors specific to an MCP server integration.

```bash
docker compose logs -f peta-core
```
Tokens:
Raw