MCP Server

Overview

Floopy exposes an MCP (Model Context Protocol) server at /mcp. Any MCP-compatible client — Claude Desktop, Cursor, Windsurf, or a custom agent — can connect to it and use Floopy tools directly within an agentic loop.

This means your AI assistant can route LLM requests through Floopy, inspect usage analytics, estimate costs, and list available models — all via standard MCP tool calls.

Authentication

Authenticate with an MCP Token passed as a Bearer token in the Authorization header:

Authorization: Bearer mcp_tbac_your_token_here

Generate MCP Tokens in the dashboard under MCP > MCP Tokens. Each token is scoped to specific permissions (e.g., read-only analytics, model listing only) and tied to your organization. No API key is needed — the MCP Token identifies your org automatically.

See MCP Tokens for details on scopes, expiration, and revocation.

Available Tools

`route_llm_request`

Routes an LLM completion request through Floopy’s gateway. Applies your configured routing rules, caching, rate limits, and firewall.

Input schema:

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Explain async/await in Rust." }
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

Output schema:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 312,
    "total_tokens": 330
  }
}

`list_models`

Returns all AI models available through your Floopy account, filtered by provider and capability.

Input schema:

{
  "provider": "openai",
  "capability": "chat"
}

Both fields are optional. Omit them to list all models.

Output schema:

{
  "models": [
    {
      "id": "gpt-4o",
      "provider": "openai",
      "capabilities": ["chat", "vision", "tool_use"],
      "context_window": 128000,
      "cost_per_million_input_tokens": 2.50,
      "cost_per_million_output_tokens": 10.00
    }
  ]
}

`estimate_cost`

Estimates the cost of a completion request before sending it. Useful for budget-aware agents.

Input schema:

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Summarize this 10-page document..." }
  ],
  "max_tokens": 500
}

Output schema:

{
  "model": "gpt-4o",
  "estimated_input_tokens": 2048,
  "estimated_output_tokens": 500,
  "estimated_cost_usd": 0.0256,
  "cheaper_alternatives": [
    {
      "model": "gpt-4o-mini",
      "estimated_cost_usd": 0.00040,
      "savings_pct": 98.4
    }
  ]
}

`get_analytics`

Fetches usage analytics for your account over a specified time range.

Input schema:

{
  "from": "2026-04-01T00:00:00Z",
  "to": "2026-04-07T23:59:59Z",
  "group_by": "model"
}

group_by accepts: model, provider, api_key, day.

Output schema:

{
  "total_requests": 14820,
  "total_tokens": 9420000,
  "total_cost_usd": 23.55,
  "cache_hit_rate": 0.34,
  "rows": [
    {
      "key": "gpt-4o",
      "requests": 4200,
      "tokens": 3100000,
      "cost_usd": 12.40
    }
  ]
}

Connecting Your Client

Claude Code supports HTTP Streamable natively:

claude mcp add floopy \
  --transport http \
  --url https://api.floopy.ai/mcp \
  --header "Authorization: Bearer mcp_tbac_your_token_here"

Replace mcp_tbac_your_token_here with an MCP Token generated in the dashboard.

Claude Desktop and claude.ai connect to remote MCP servers via Custom Connectors:

Open Claude Desktop or go to claude.ai
Navigate to Settings > Connectors
Scroll down and click Add custom connector
Enter the URL: https://api.floopy.ai/mcp
Complete the authentication flow

After connecting, Floopy tools will appear in the attachment menu (paperclip icon) and can be used directly in conversations.

Custom Connectors use OAuth for authentication. OAuth support for the Floopy MCP Server is coming soon. In the meantime, use Claude Code CLI which supports Bearer token auth natively.

Open Settings > Features > MCP Servers and add:

{
  "floopy": {
    "url": "https://api.floopy.ai/mcp",
    "headers": {
      "Authorization": "Bearer mcp_tbac_your_token_here"
    }
  }
}

After saving, Cursor will load the Floopy tool list automatically.

Any MCP-compatible client can connect via HTTP Streamable transport:

POST https://api.floopy.ai/mcp
Content-Type: application/json
Authorization: Bearer mcp_tbac_your_token_here

{"jsonrpc":"2.0","method":"initialize","params":{},"id":"1"}

Example with 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.floopy.ai/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer mcp_tbac_your_token_here",
      },
    },
  },
);

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

// List available tools
const tools = await client.listTools();
console.log("Available tools:", tools);

// Call a tool
const result = await client.callTool({
  name: "list_models",
  arguments: {},
});
console.log("Models:", result);

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

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

await client.connect(
  new StreamableHTTPClientTransport(
    new URL("https://api.floopy.ai/mcp"),
    {
      headers: {
        Authorization: `Bearer ${process.env.FLOOPY_API_KEY}`,
      },
    }
  )
);

const result = await client.callTool({
  name: "estimate_cost",
  arguments: {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello, world!" }],
    max_tokens: 100,
  },
});

console.log(result.content);

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

async def main():
    async with streamablehttp_client(
        "https://api.floopy.ai/mcp",
        headers={"Authorization": f"Bearer {os.environ['FLOOPY_API_KEY']}"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "list_models",
                arguments={"provider": "anthropic"},
            )
            print(result.content)

asyncio.run(main())

Error Codes

HTTP Status	Meaning
`401`	Missing or invalid API key / MCP Token
`403`	Token lacks required scope for this tool
`429`	Rate limit exceeded
`400`	Invalid tool input (see error message for details)
`500`	Gateway error — open a support ticket