# Skillwire: Universal Model Context Protocol (MCP) Gateway & Agent Skill Router
# Comprehensive Technical Specification & Full Documentation

> Document version: 1.2.0 (October 2026)  
> Protocol standard: Model Context Protocol (MCP) v1 (Streamable HTTP & SSE)  
> Entrypoints: `https://skillwire.dev/mcp` (Streamable HTTP) | `https://skillwire.dev/sse` (Server-Sent Events)  
> Machine Manifests: [/llms.txt](https://skillwire.dev/llms.txt) | [/agent.md](https://skillwire.dev/agent.md) | [/sitemap.xml](https://skillwire.dev/sitemap.xml)

---

## 1. Executive Summary & Problem Statement

Skillwire is a high-performance Universal Model Context Protocol (MCP) Gateway and Agent Skill Router. It bridges autonomous AI models (such as Anthropic Claude, OpenAI GPT-4o, Cursor, Google Antigravity, and open-source agent runtimes) with external APIs, SaaS endpoints, databases, and microservices.

### The Problem Skillwire Solves
1. **Prompt Context Bloat (Schema Stomping)**: Embedding dozens or hundreds of OpenAPI JSON schemas into an LLM's system prompt consumes tens of thousands of tokens before execution begins, dramatically increasing API inference costs and reducing model attention.
2. **Verbosity of Upstream Payloads**: Typical REST and GraphQL responses contain large volumes of nested metadata, formatting wrappers, and irrelevant keys (often 10 KB to 150 KB). Returning these raw payloads floods the context window and triggers prompt truncation.
3. **Credential Vulnerability**: Passing sensitive third-party API keys (e.g., Stripe secret keys, GitHub tokens, AWS credentials) into LLM prompts or chat histories risks permanent leakage in logs, fine-tuning datasets, and prompt injections.
4. **Tool Selection Accuracy**: When models choose between dozens of similar tools, hallucination rates spike. Skillwire uses hybrid semantic search to dynamically retrieve only the top 3-5 relevant tools on demand.

### The Solution
Skillwire acts as a sub-50ms gateway that dynamically routes tool calls, compresses verbose payloads using in-memory response distillation, and protects credentials via hardware-isolated AES-256-GCM vaulting.

---

## 2. Key Architecture & Quantitative Benchmarks

| Metric / Specification | Value / Guarantee | Verifiable Source / Standard |
| :--- | :--- | :--- |
| **Median Discovery Latency (P50)** | 14.2 ms | Hybrid BM25 + Vector Cosine Sim + RRF |
| **Total Gateway Overhead** | 18.2 ms | Ingress + Discovery + Vault + SSRF + Distill |
| **Maximum Token Distillation** | Up to 94% reduction | Schema-guided in-memory field extraction |
| **Catalog Capacity** | 294 API tools · 1,029 prompt skills (1,323 total) | Curated provider ecosystem & OpenAPI importer |
| **Credential Vault Security** | AES-256-GCM hardware-isolated | Host-bound (*.stripe.com) & zero plaintext logs |
| **SSRF Network Defense** | 16 IPv4 & 11 IPv6 blocked subnets | RFC 1918, RFC 4291, zero redirect following |
| **Active Stream Revocation** | 15-second sweeper | Immediate termination of revoked project keys |
| **Supply-Chain Gate Cycle** | 72 hours automated | NVIDIA SkillSpector AST & SPDX license checks |

---

## 3. Protocol Implementations

Skillwire supports all standard connection transports defined by the Model Context Protocol:

### A. Streamable HTTP (`POST /mcp`) — Recommended (MCP 2025+)
Modern streaming transport providing single-socket request/response streaming:
- **Endpoint**: `https://skillwire.dev/mcp`
- **Method**: `POST`
- **Headers**:
  - `Content-Type: application/json`
  - `Authorization: Bearer sw_live_YOUR_KEY` (or `X-API-KEY: sw_live_YOUR_KEY`)
- **Body**: Standard JSON-RPC 2.0 messages (`initialize`, `tools/list`, `tools/call`).

### B. Server-Sent Events (`GET /sse`) — Legacy Streaming
Standard SSE streaming for Claude Desktop and legacy agent clients:
- **Endpoint**: `https://skillwire.dev/sse`
- **Method**: `GET`
- **Headers**:
  - `Accept: text/event-stream`
  - `Authorization: Bearer sw_live_YOUR_KEY`
- Returns an initial `endpoint` event containing the POST target for JSON-RPC messages.

### C. Registered MCP Tools Exposed to AI Clients
When an AI agent initializes Skillwire over MCP, the gateway exposes these primary tools:
1. `search_skills`:
   - Description: Perform hybrid semantic search across the 294 API tool and 1,029 prompt skill catalog (1,323 total) using natural language. Automatically inlines top prompt guidance for zero-friction single-hop execution.
   - Arguments: `query` (string), `inline_content` (boolean, optional, default true).
2. `execute_skill`:
   - Description: Execute any tool in the Skillwire catalog by its ID with parameter arguments. Performs deterministic structural pruning and optional semantic distillation.
   - Arguments: `skill_id` (string), `parameters` (object).
3. `retrieve_payload`:
   - Description: Retrieve full raw payloads or extended output from a previous skill execution using `raw_ref_id`.
   - Arguments: `raw_ref_id` (string).
4. `read_prompt_skill`:
   - Description: Fetch the complete, un-truncated engineering standard, design rules, or architectural guidance for any indexed prompt skill.
   - Arguments: `skill_name` (string).

---

## 4. In-Memory Response Distillation Engine

Skillwire's distillation engine prunes upstream JSON payloads before they reach the language model:
- **Heuristic & Schema Filtering**: Eliminates redundant metadata, null fields, tracking cookies, and decorative arrays.
- **Structured Markdown Synthesis**: Converts complex data into high-density Markdown bullet points and tables.
- **Agent Opt-Out**: Agents requiring exact raw JSON can pass `"distill": false` in tool parameters.
- **Capped Payloads & Reference Handles**: If raw responses exceed 1 MB, Skillwire stores the full response in a short-lived cache and returns a `raw_ref_id` allowing pagination via `retrieve_payload`.

### Token Savings Example: Stripe Charge Failure
- **Raw API JSON**: 24.8 KB (~6,200 tokens)
- **Distilled Markdown Fact Sheet**: 412 Bytes (~105 tokens)
- **Token Cost Reduction**: 98.3%

---

## 5. Zero-Trust BYOK Credential Vault

Skillwire incorporates a hardware-isolated Bring-Your-Own-Key (BYOK) credential vault:
1. **Cryptographic Encryption**: Vendor keys (e.g. OpenAI, Stripe, GitHub, Twilio) are encrypted at rest using AES-256-GCM with PBKDF2 key derivation and random initialization vectors (IV).
2. **Domain-Scoped Binding**: Each credential is bound to a specific hostname pattern (e.g., `*.stripe.com`). The gateway kernel enforces that credentials can never be attached to out-of-domain requests.
3. **Master-Secret Blacklist**: Prevents accidental leakage of platform environment variables (`DATABASE_URL`, `JWT_SECRET`, `ADMIN_KEY`).
4. **Downstream Injection Only**: Credentials are injected into outbound HTTP request headers immediately before socket dispatch and scrubbed from all logging, traces, and LLM responses.

---

## 6. SSRF Protection & Network Boundary Rules

All external calls pass through the `SSRFValidator` kernel:
- **Private Subnets Blocked**: Blocks `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `169.254.169.254` (cloud metadata), and IPv6 loopback/link-local ranges (`::1`, `fe80::/10`, `fc00::/7`).
- **IPv6 Normalization**: Strips surrounding brackets (`[::1]` -> `::1`) prior to CIDR evaluation.
- **DNS-Rebinding Pinning**: Performs dual DNS resolution at validation time and pins destination sockets to verified public IPs, forbidding external HTTP redirects.

---

## 7. REST API Reference

All requests accept `Authorization: Bearer <API_KEY>` or `X-API-KEY: <API_KEY>`.

### 1. Healthcheck
- `GET /api/health`
- Auth: None
- Response: `{"status": "ok", "uptime": 12849, "database": "connected"}`

### 2. Search Skills
- `POST /api/skills/search`
- Auth: Required
- Body: `{"query": "extract tables from pdf", "limit": 5}`
- Response: Array of matched skills with description, parameter schemas, and relevance score.

### 3. Get Skill Schema
- `GET /api/skills/{skillId}/schema`
- Auth: None
- Response: JSON Schema of input parameters for `{skillId}`.

### 4. Execute Skill
- `POST /api/skills/{skillId}/execute`
- Auth: Required
- Body: `{"parameters": {"url": "https://example.com/doc.pdf"}, "distill": true}`
- Response:
  ```json
  {
    "success": true,
    "skill_id": "pdf-extractor",
    "execution_time_ms": 138,
    "was_distilled": true,
    "content": "..."
  }
  ```

### 5. Import OpenAPI Specification
- `POST /api/skills/import-openapi`
- Auth: Required
- Body: `{"url": "https://api.example.com/openapi.json", "category": "finance"}`
- Response: `{"success": true, "skills_created": 12}`

### 6. User Credential Vault (BYOK)
- `GET /api/user/credentials`: List saved credentials (masked).
- `POST /api/user/credentials`: Save or update a credential with `provider`, `key_value`, and optional `domain_scope`.
- `POST /api/user/credentials/delete`: Remove a stored credential by `provider`.

---

## 8. Client Setup Configurations

### A. Cursor Configuration (`~/.cursor/mcp.json` or Project Settings)
```json
{
  "mcpServers": {
    "skillwire": {
      "url": "https://skillwire.dev/mcp",
      "headers": {
        "Authorization": "Bearer sw_live_YOUR_PROJECT_KEY"
      }
    }
  }
}
```

### B. Anthropic Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "skillwire": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://skillwire.dev/sse",
        "--header",
        "Authorization: Bearer sw_live_YOUR_PROJECT_KEY"
      ]
    }
  }
}
```

### C. Google Antigravity Configuration
```json
{
  "mcpServers": {
    "skillwire": {
      "url": "https://skillwire.dev/mcp",
      "headers": {
        "Authorization": "Bearer sw_live_YOUR_PROJECT_KEY"
      }
    }
  }
}
```

### D. Windsurf (`mcp_config.json`)
```json
{
  "mcpServers": {
    "skillwire": {
      "serverUrl": "https://skillwire.dev/sse",
      "headers": {
        "Authorization": "Bearer sw_live_YOUR_PROJECT_KEY"
      }
    }
  }
}
```

### E. Python SDK & LangChain
```python
import os
import requests

API_KEY = os.getenv("SKILLWIRE_API_KEY")
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Search for relevant skills dynamically
response = requests.post(
    "https://skillwire.dev/api/skills/search",
    json={"query": "scrape website content to markdown"},
    headers=HEADERS
)
skills = response.json()["skills"]
skill_id = skills[0]["id"]

# Execute skill with automatic distillation
exec_result = requests.post(
    f"https://skillwire.dev/api/skills/{skill_id}/execute",
    json={"parameters": {"url": "https://news.ycombinator.com"}, "distill": True},
    headers=HEADERS
)
print(exec_result.json()["content"])
```

---

## 9. Frequently Asked Questions (FAQ)

### Q: What is an MCP Gateway and how is it different from local MCP servers?
**A**: A local MCP server runs as a separate subprocess for every tool, consuming memory and requiring local installation of Python/Node runtimes and manual credential configuration. Skillwire acts as a centralized gateway in the cloud or self-hosted in your VPC. It makes 294 API tools and 1,029 prompt skills available through its gateway and uses semantic search to expose relevant tools on demand.

### Q: How does response distillation prevent context overflow?
**A**: Modern LLMs have context limits, but more importantly, retrieval accuracy deteriorates as context length increases ("lost in the middle"). By filtering out repetitive JSON boilerplate, HTTP metadata, and unused nested objects, Skillwire passes concise, structured facts directly to the model, saving up to 94% tokens.

### Q: Are my API credentials safe with Skillwire?
**A**: Yes. Skillwire uses a Zero-Trust architecture. Your vendor API keys are encrypted at rest with AES-256-GCM. They are bound to strict hostname patterns (e.g. `*.stripe.com`) and are injected strictly into downstream outbound HTTP sockets. They are never logged, never returned in API responses, and never visible to the AI model.

### Q: What is the latency overhead introduced by Skillwire?
**A**: The median discovery latency is 14.2 ms. Total gateway processing overhead (including SSL ingress, semantic discovery, vault decryption, SSRF check, and payload distillation) is 18.2 ms, making it virtually imperceptible compared to standard LLM inference times (typically 500ms to 3000ms).

### Q: Does Skillwire support self-hosting?
**A**: Yes. Skillwire can be deployed on Docker Compose, AWS ECS, GCP Cloud Run, or Kubernetes with PostgreSQL and Redis backends. Enterprise licenses include Terraform modules and Helm charts for air-gapped VPC deployments.

---

## 10. Legal, Privacy, & Machine Discovery Links

- **Main Website**: [https://skillwire.dev](https://skillwire.dev)
- **Interactive Documentation**: [https://skillwire.dev/docs](https://skillwire.dev/docs)
- **Technical Specifications**: [https://skillwire.dev/features](https://skillwire.dev/features)
- **Pricing & Quotas**: [https://skillwire.dev/pricing](https://skillwire.dev/pricing)
- **Autonomous Agent Entry**: [https://skillwire.dev/agent.md](https://skillwire.dev/agent.md)
- **Context Map**: [https://skillwire.dev/llms.txt](https://skillwire.dev/llms.txt)
- **XML Sitemap**: [https://skillwire.dev/sitemap.xml](https://skillwire.dev/sitemap.xml)
- **Terms of Service**: [https://skillwire.dev/terms](https://skillwire.dev/terms)
- **Privacy Policy**: [https://skillwire.dev/privacy-policy](https://skillwire.dev/privacy-policy)
- **Contact Sales**: [https://skillwire.dev/contact-sales](https://skillwire.dev/contact-sales)