MCP Server

Visao Geral

O Floopy expoe um servidor MCP (Model Context Protocol) em /mcp. Qualquer cliente compativel com MCP — Claude Desktop, Cursor, Windsurf ou um agente customizado — pode se conectar e usar as ferramentas do Floopy diretamente em um agent loop.

Isso significa que seu assistente de IA pode rotear requisicoes LLM pelo Floopy, inspecionar analytics de uso, estimar custos e listar modelos disponiveis — tudo via chamadas de ferramentas MCP padrão.

Autenticacao

Autentique com um Token MCP passado como Bearer token no header Authorization:

Authorization: Bearer mcp_tbac_seu_token_aqui

Gere Tokens MCP no dashboard em MCP > Tokens MCP. Cada token tem escopo de permissoes especificas (por exemplo, apenas leitura de analytics, apenas listagem de modelos) e esta vinculado a sua organizacao. Nao e necessario enviar API key — o Token MCP identifica sua org automaticamente.

Veja Tokens MCP para detalhes sobre escopos, expiracao e revogacao.

Ferramentas Disponiveis

route_llm_request

Roteia uma requisicao de completion LLM pelo gateway do Floopy. Aplica suas regras de roteamento, cache, rate limits e firewall configurados.

Schema de entrada:

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

Schema de saida:

{
  "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

Retorna todos os modelos de IA disponiveis na sua conta Floopy, filtrados por provider e capacidade.

Schema de entrada:

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

Ambos os campos sao opcionais. Omita-os para listar todos os modelos.

Schema de saida:

{
  "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

Estima o custo de uma requisicao de completion antes de envia-la. Util para agentes conscientes de orcamento.

Schema de entrada:

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Resuma este documento de 10 paginas..." }
  ],
  "max_tokens": 500
}

Schema de saida:

{
  "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

Busca analytics de uso da sua conta em um intervalo de tempo especificado.

Schema de entrada:

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

group_by aceita: model, provider, api_key, day.

Schema de saida:

{
  "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
    }
  ]
}

Conectando Seu Client

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

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

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

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

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_seu_token_aqui",
      },
    },
  },
);

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

// Listar ferramentas disponiveis
const tools = await client.listTools();
console.log("Ferramentas:", tools);

// Chamar uma ferramenta
const result = await client.callTool({
  name: "list_models",
  arguments: {},
});
console.log("Modelos:", result);

Codigos de Erro