MCP Setup & Usage

RESTK implements a local Model Context Protocol (MCP) server that lets AI coding assistants interact with your API collections. This guide covers setup, capabilities, and real-world usage patterns. For a high-level overview of AI capabilities, see AI Integration.

---

Setting Up the MCP Server

One-Click Setup (Recommended)

Manual Setup — Claude Code

claude mcp add --transport stdio --scope user restk -- /Applications/Restk.app/Contents/Resources/restk-bridge

Manual Setup — Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "restk": {
      "command": "/Applications/Restk.app/Contents/Resources/restk-bridge"
    }
  }
}

Manual Setup — Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "restk": {
      "url": "http://localhost:52452/mcp"
    }
  }
}

No Node.js or npx required for any platform.

---

Connection Lifecycle

---

Confirmation & Approval Flow

RESTK categorizes operations by their impact level:

Read-only (no approval needed):

• Browsing collections, folders, requests, and mock servers
• Reading request details and configurations
• Accessing environment variable names and non-secret values
• Analyzing responses, performance data, and error patterns
• Searching across responses
• Generating test script previews and inferring schemas
• Exporting requests as cURL commands
• Analyzing mock server coverage

Non-destructive writes (approval required):

• Creating or updating collections, requests, folders, and environments
• Executing requests and cURL commands
• Importing collections
• Creating and configuring mock servers
• Adding mock server responses and routing rules
• Generating and saving readiness reports
• Starting and stopping mock servers

Destructive operations (always require manual approval):

• Deleting collections, requests, or folders
• Deleting mock servers, mock responses, or routing rules

When a write operation is requested, RESTK displays a confirmation dialog showing exactly what the AI wants to do. If you don't respond within the timeout window, the action is automatically denied.

Auto-Approve Option

For workflows where you trust the AI client and want faster iteration, you can enable auto-approve in Settings → AI Integration. When enabled, non-destructive write operations (create, update, execute) proceed without a confirmation dialog. Destructive operations (delete) always require manual approval regardless of the auto-approve setting.

---

What You Can Do

RESTK exposes 47 tools to AI clients. You don't need to know tool names — just describe what you want in plain English. Your AI assistant maps your request to the right capability automatically.

Browse & Read

View your API workspace without any approval required.

Execute & Export

Run requests and export them for use outside RESTK.

Create & Organize

Build and manage your API workspace.

Analyze & Debug

Inspect responses, find patterns, and diagnose issues.

AI-Powered Analysis

Deep analysis powered by AI with deterministic fallbacks.

AI Workflows

Advanced multi-step workflows that combine multiple capabilities.

Agent Readiness

Mock Server

Create and manage mock servers for testing without a live backend.

---

Available Resources

RESTK exposes 10 read-only data resources that AI clients can access for structured context without invoking tools. Resources use restk:// URIs.

Resources follow the same visibility rules as tools — only AI-shared collections and their contents are accessible.

---

Prompts

RESTK registers 6 MCP prompts that provide guided AI workflows. Prompts are available to AI clients that support the MCP prompts capability — they surface as structured starting points for complex tasks.

---

Quick Reference

---

Real-World Usage Examples

Debugging a Failing Endpoint

Scenario: Your /api/orders endpoint returns 500 intermittently.

You: "The orders endpoint keeps failing. Can you check the recent responses
     and find a pattern?"

AI: Reads the request details, pulls execution history, and analyzes
    error patterns.

AI: "I found 12 responses in the last hour. 4 returned 500 with the message
    'connection pool exhausted'. All failures happened during batch operations
    with more than 50 items. The endpoint works fine for smaller payloads.
    Likely a backend connection pool limit."

Building a New Integration

Scenario: You have API docs for a payment gateway and want to set up a collection fast.

You: "Create a Payment Gateway collection with endpoints for
     create charge, get charge, list charges, and refund.
     Base URL is https://api.payments.example.com/v1"

AI: Creates the collection, then creates four requests (with approval
    for each). Sets up proper methods, URLs, headers, and placeholder bodies
    based on standard REST conventions.

You: "Now generate test scripts for the create charge endpoint"

AI: Generates test assertions for status code, response structure,
    and required fields (no approval needed — read-only preview).

Performance Review

Scenario: Your team wants to know which endpoints are slowest before a release.

You: "Analyze performance across my Staging API collection and
     find the slowest endpoints"

AI: Runs performance analysis on the collection, then pulls detailed
    timelines for the outliers.

AI: "Across 34 endpoints, average response time is 180ms. Three endpoints
    exceed 1 second:
    - POST /api/reports/generate — 3.2s (DNS: 12ms, Server: 3100ms)
    - GET /api/search — 1.8s (DNS: 10ms, Server: 1750ms)
    - POST /api/import — 1.4s (DNS: 11ms, Server: 1350ms)
    All three have high server processing time. The reports endpoint
    is the main bottleneck."

Mock Server for Frontend Testing

Scenario: Your frontend team needs a mock API while the backend is still in development.

You: "Create a mock server from my User API collection"

AI: Creates a mock server with routes matching your real endpoints.
    Generates realistic response data based on your existing responses.

You: "Add error responses for the login endpoint — 401 for bad credentials
     and 429 for rate limiting"

AI: Adds custom response variants with appropriate status codes,
    headers, and body content.

You: "Start the mock server"

AI: Starts the server on a local port. Your frontend can now hit
    the mock endpoints during development.

---

Troubleshooting

Advanced Troubleshooting

Port Discovery

RESTK's MCP server defaults to port 52452. If that port is occupied, RESTK automatically selects an available port. The active port is written to a discovery file:

~/Library/Application Support/Restk/mcp.port

If your AI client cannot connect on the default port, read this file to find the actual port RESTK is using.

MCP Server Logs

If you need to diagnose connection issues, check the MCP server log in RESTK:

1. Open Settings → AI Integration
2. Click View MCP Logs
3. Look for connection errors, initialization failures, or tool execution errors

---

Next Steps