MCP Connection

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents discover and invoke external tools through a structured transport. When you connect Squillify as an MCP server, your agent gets three gateway tools that open up the full MicroSkill catalog assigned to your API key.

We use a gateway pattern to keep things simple for you: instead of flooding your agent with hundreds of individual MicroSkills as MCP tools, we expose three foundation tools that let it search the catalog, pull up MicroSkill contracts, and run MicroSkills on demand. Server instructions walk the agent through this workflow automatically.

The upshot: your agent doesn’t need any custom code to call Squillify. It connects, receives the gateway tools and instructions, and uses them to discover and invoke MicroSkills natively — just like any other tool.

Squillify MCP endpoint

There’s just one endpoint to point your agent at:

• https://api.squillify.com/mcp— Streamable HTTP transport. This is the only MCP endpoint, and it’s stateless and request/response: every tool call stands on its own, so your client never has to manage a session, and your integration keeps humming along across restarts and deploys.

Authenticate with your Squillify API key — the same one you already use for REST calls. Send it as the X-API-Key header, or as Authorization: Bearer sq_live_...if that’s easier for your client. Both work.

Gateway tools

When your agent connects, it receives exactly three MCP tools — here’s what each one does for you:

The flow your agent follows is: search → contract (optional) → execute.

You don’t have to teach it that pattern — the server instructions we deliver at connection time guide the agent through it automatically. Most MCP clients (Claude, Cursor, custom agents) follow these instructions without any extra configuration from you.

Configure Claude Desktop

Adding Squillify to Claude Desktop takes just one config change. Open (or create) the file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "squillify": {
      "url": "https://api.squillify.com/mcp",
      "headers": {
        "X-API-Key": "sq_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop and you’re set — Claude picks up the three gateway tools and server instructions. Whenever it needs a capability — slugifying text, validating data, generating signatures — it’ll search the catalog, retrieve the contract if needed, and execute the MicroSkill on its own.

Configure Cursor

Wiring up Cursor is just as quick. Create or edit .cursor/mcp.json in your project root (or globally at ~/.cursor/mcp.json):

{
  "mcpServers": {
    "squillify": {
      "url": "https://api.squillify.com/mcp",
      "headers": {
        "X-API-Key": "sq_live_your_key_here"
      }
    }
  }
}

Once that’s in place, Cursor’s agent can discover and invoke your Squillify MicroSkills right in your coding sessions, all through the gateway tools.

Configure a custom agent

Building your own agent or using an MCP client library? You can connect to Squillify programmatically. Here’s an example using the MCP TypeScript SDK:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api.squillify.com/mcp"),
  {
    requestInit: {
      headers: {
        "X-API-Key": process.env.SQUILLIFY_API_KEY!,
      },
    },
  }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// List gateway tools
const { tools } = await client.listTools();
console.log("Gateway tools:", tools.map(t => t.name));
// → ["platform.skill_catalog_search", "platform.skill_contract_get", "platform.skill_execute"]

// Search for a skill
const search = await client.callTool({
  name: "platform.skill_catalog_search",
  arguments: { query: "slugify text", limit: 3 },
});
console.log("Search results:", search.content);

// Execute a skill through the gateway
const result = await client.callTool({
  name: "platform.skill_execute",
  arguments: {
    skill_name: "text.slugify",
    arguments: { text: "Hello World — My First MCP Call" },
  },
});

console.log("Result:", result.content);

Python example

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        "https://api.squillify.com/mcp",
        headers={"X-API-Key": "sq_live_your_key_here"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List gateway tools
            tools = await session.list_tools()
            for tool in tools.tools:
                print(f"  {tool.name}: {tool.description}")

            # Search for a skill
            search = await session.call_tool(
                "platform.skill_catalog_search",
                arguments={"query": "slugify text", "limit": 3}
            )
            print("Search:", search.content)

            # Execute a skill through the gateway
            result = await session.call_tool(
                "platform.skill_execute",
                arguments={
                    "skill_name": "text.slugify",
                    "arguments": {"text": "Hello from Python"}
                }
            )
            print("Result:", result.content)

How it works

Curious what happens behind the scenes when your agent connects to Squillify over MCP? Here’s the play-by-play:

1. We validate your API key and resolve its MicroSkill grants.
2. We expose the three gateway tools: search, contract retrieval, and execution.
3. We deliver server instructions that guide the agent through the search → contract → execute workflow.
4. Your LLM uses the gateway tools to discover the capabilities it needs, retrieve their contracts, and invoke them as part of its reasoning.
5. Every MicroSkill invocation through platform.skill_executeis authenticated, authorized, metered, and logged — exactly like a REST call.

Connection reliability & performance (HTTP/2)

Squillify sits behind an HTTP/2 edge (a CDN/load balancer) that terminates TLS and HTTP/2 for you and forwards requests to our origin over HTTP/1.1. You’ll never see this directly — but it has one practical consequence worth designing for: the edge owns the lifecycle of your HTTP/2 connections and will periodically recycle them.

Expect (and handle) HTTP/2 GOAWAY

Under sustained traffic, the edge sends an HTTP/2 GOAWAYframe to ask your client to stop opening new streams on a connection and move to a fresh one. This happens once a connection reaches a maximum number of requests or a maximum age. It’s normal, graceful connection hygiene — not a server error and not rate limiting (rate limiting comes back as an HTTP 429, never a transport reset).

GOAWAY is safe by design: streams the edge already accepted finish normally, and any stream it had notstarted processing is safe to retry on a new connection (the request never reached us, so retrying can’t double-execute it).

Here’s what your client should do:

• Retry on transport reset. If a request fails with GOAWAY received, a connection reset, or a refused stream, quietly retry it on a new connection with a short exponential backoff (e.g. 50ms → 200ms → 800ms, a few attempts). These aren’t application errors.
• Don’t count GOAWAY as a failure. Treat it like a reconnect, not an outage.

Pool multiple connections for high throughput

For anything beyond light, interactive use — batch jobs, high-RPS agents, load tests — open a pool of 4–8 HTTP/2 connections per client and spread requests across them (round-robin) rather than multiplexing everything onto a single connection.

Here’s why it matters: with a single connection, every in-flight multiplexed stream fails together the moment that connection is recycled by a GOAWAY. Spreading across N connections cuts the blast radius of any single recycle to 1/N and keeps your throughput flat. In our own load tests, a single-connection HTTP/2 client saw sporadic stream resets under burst load, while ≥4 connections eliminated them entirely at the same offered load.

Timeouts

• Connect timeout: ~10–15s.
• Read timeout: ≥30s (≥60s if you call heavy skills such as document rendering or archive creation, whose execution can take hundreds of ms to a few seconds).

Throughput, rate limits & metering

Size your concurrency around how we meter MCP traffic — it’s identical to REST:

• platform.skill_catalog_search and platform.skill_contract_get are foundation calls: they don’t consume your tenant rate limit or quota. Discovery is free.
• Only platform.skill_execute consumes tenant RPM and quota, charged once per execution.
• So your effective ceiling is your tenant RPM applied to executions, not to every JSON-RPC call — search and read contracts as liberally as you like; it costs nothing against your limits.
• A 429means you’ve exceeded your tenant rate limit. It’s rare under normal use; back off and retry with jitter. (Unlike GOAWAY, a 429 is an application-level signal to slow down.)

Quick checklist for a robust custom client

• Pool 4–8 HTTP/2 connections, round-robin requests across them.
• Retry GOAWAY / connection-reset / refused-stream on a fresh connection with backoff.
• Distinguish transport resets (retry transparently) from 429 (back off) and 5xx (back off).
• Connect timeout ~10–15s, read timeout ≥30–60s.
• Send the API key via the X-API-Key header (never in the URL).
• Search/contract freely; budget concurrency against tenant RPM for platform.skill_execute.

Single transport (no /sse)

Squillify exposes a single MCP transport: Streamable HTTP at /mcp. There’s no /sseendpoint — so if you stumble on an older guide that points there, you can safely ignore it. Requests to /ssearen’t served and will be turned away. Point every MCP client at https://api.squillify.com/mcpand you’re set.