O desenvolvimento de IA está evoluindo rapidamente, e integrar ferramentas externas com modelos de linguagem é um passo crítico para frente. OpenRouter oferece uma API unificada para acessar inúmeros modelos de linguagem, enquanto os Servidores MCP (Model Context Protocol Servers) permitem que esses modelos executem ferramentas externas e acessem dados em tempo real. Combiná-los cria um sistema poderoso para construir aplicações avançadas de IA.
Neste post, vou orientá-lo sobre como integrar os Servidores MCP com o OpenRouter. Você aprenderá suas funcionalidades principais, o processo de integração e exemplos práticos.
Entendendo os Servidores MCP e o OpenRouter
Para integrar os Servidores MCP com o OpenRouter, você precisa primeiro compreender o que cada componente faz.
OpenRouter: Acesso Unificado a Modelos de Linguagem
OpenRouter é uma plataforma que simplifica a interação com grandes modelos de linguagem (LLMs) de provedores como OpenAI, Anthropic e xAI. Oferece um único endpoint de API https://openrouter.ai/api/v1/chat/completions compatível com a estrutura da API da OpenAI. As principais características incluem:
- Agregação de Modelos: Acesse centenas de LLMs através de uma única interface.
- Otimização de Custos: Roteia solicitações para modelos econômicos com base na disponibilidade e preços.
- Balanceamento de Carga: Distribui solicitações para evitar sobrecarga em qualquer provedor único.
- Fallbacks: Troca para modelos alternativos se um falhar.
Você precisará de uma conta no OpenRouter e uma chave de API para prosseguir. Adquira a sua em openrouter.ai.
Servidores MCP: Ampliando as Capacidades do Modelo
Servidores MCP implementam o Protocolo de Contexto de Modelo, permitindo que LLMs chamem ferramentas externas. Ao contrário de modelos independentes limitados a seus dados de treinamento, os Servidores MCP permitem interação em tempo real com sistemas como diretórios de arquivos, bancos de dados ou APIs de terceiros. Uma definição típica de ferramenta MCP inclui:
- Nome: Identifica a ferramenta (por exemplo,
list_files). - Descrição: Explica seu propósito.
- Parâmetros: Especifica entradas no formato JSON Schema.
Por exemplo, uma ferramenta MCP para listar arquivos de diretório pode ser assim:
{
"name": "list_files",
"description": "Lista arquivos em um diretório especificado",
"parameters": {
"type": "object",
"properties": {
"path": {"type": "string", "description": "Caminho do diretório"}
},
"required": ["path"]
}
}
Juntos, OpenRouter fornece o modelo e Servidores MCP abastecem as ferramentas, formando um robusto ecossistema de IA.
Por que Integrar os Servidores MCP com o OpenRouter?
A combinação dessas tecnologias oferece várias vantagens técnicas:
- Flexibilidade do Modelo: Utilize qualquer LLM compatível com OpenRouter com capacidades de chamada de ferramentas.
- Redução de Custos: Combine modelos mais baratos com ferramentas externas para descarregar tarefas complexas.
- Capacidades Aprimoradas: Permita que os modelos acessem dados em tempo real ou realizem ações (por exemplo, operações em arquivos).
- Escalabilidade: Troque modelos ou ferramentas sem reescrever sua lógica central.
- Preparação para o Futuro: Adapte-se a novos LLMs e ferramentas à medida que surgirem.
Essa integração é ideal para desenvolvedores que constroem sistemas de IA que precisam de interatividade do mundo real.
Processo de Integração Passo a Passo
Agora, vamos aos detalhes técnicos. Aqui está como integrar os Servidores MCP com o OpenRouter.
Pré-requisitos
Garanta que você tenha:
- Conta e Chave de API do OpenRouter: Do openrouter.ai.
- Servidor MCP: Executando localmente (por exemplo, em
http://localhost:8000) ou remotamente. Para este guia, usarei um servidor MCP de sistema de arquivos. - Python 3.8+: Com a biblioteca
requests(pip install requests). - Apidog: Opcional, mas recomendado para teste de API. Baixe gratuitamente.
Passo 1: Definir e Converter Ferramentas MCP
OpenRouter utiliza o formato de chamada de ferramentas da OpenAI, então você deve converter as definições de ferramentas MCP. Comece com a definição MCP:
{
"name": "list_files",
"description": "Lista arquivos em um diretório especificado",
"parameters": {
"type": "object",
"properties": {
"path": {"type": "string", "description": "Caminho do diretório"}
},
"required": ["path"]
}
}
Converta-a para o formato da OpenAI adicionando um campo type e aninhando os detalhes da função:
{
"type": "function",
"function": {
"name": "list_files",
"description": "Lista arquivos em um diretório especificado",
"parameters": {
"type": "object",
"properties": {
"path": {"type": "string", "description": "Caminho do diretório"}
},
"required": ["path"]
}
}
}
Essa estrutura JSON é o que o OpenRouter espera em seu payload de API.
Passo 2: Configurar a Solicitação de API
Prepare uma solicitação de API para o OpenRouter. Defina os cabeçalhos com sua chave de API e um payload com o modelo, mensagens e ferramentas. Aqui está um exemplo em Python:
import requests
import json
# Headers
headers = {
"Authorization": "Bearer your_openrouter_api_key",
"Content-Type": "application/json"
}
# Payload
payload = {
"model": "openai/gpt-4", # Substitua pelo seu modelo preferido
"messages": [
{"role": "user", "content": "Liste os arquivos no diretório atual."}
],
"tools": [
{
"type": "function",
"function": {
"name": "list_files",
"description": "Lista arquivos em um diretório especificado",
"parameters": {
"type": "object",
"properties": {
"path": {"type": "string", "description": "Caminho do diretório"}
},
"required": ["path"]
}
}
}
]
}
Substitua your_openrouter_api_key pela sua chave real.
Passo 3: Enviar a Solicitação Inicial de API
Faça uma solicitação POST para o endpoint do OpenRouter:
response = requests.post(
"https://openrouter.ai/api/v1/chat/completions",
headers=headers,
json=payload
)
response_data = response.json()
Passo 4: Processar Chamadas de Ferramentas
Verifique se a resposta inclui uma chamada de ferramenta:
{
"choices": [
{
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_123",
"type": "function",
"function": {
"name": "list_files",
"arguments": "{\"path\": \".\"}"
}
}
]
}
}
]
}
Extraia os detalhes da chamada da ferramenta:
message = response_data["choices"][0]["message"]
if "tool_calls" in message:
tool_call = message["tool_calls"][0]
function_name = tool_call["function"]["name"]
arguments = json.loads(tool_call["function"]["arguments"])
Passo 5: Chamar o Servidor MCP
Envie a solicitação da ferramenta para o seu Servidor MCP:
mcp_response = requests.post(
"http://localhost:8000/call",
json={
"name": function_name,
"arguments": arguments
}
)
tool_result = mcp_response.json()["result"] # e.g., ["file1.txt", "file2.txt"]
Passo 6: Retornar o Resultado da Ferramenta ao OpenRouter
Anexe a chamada da ferramenta do assistente e o resultado ao histórico de mensagens:
messages = payload["messages"] + [
{
"role": "assistant",
"content": null,
"tool_calls": [tool_call]
},
{
"role": "tool",
"tool_call_id": tool_call["id"],
"content": json.dumps(tool_result)
}
]
# Atualize o payload
payload["messages"] = messages
# Envie a solicitação de acompanhamento
final_response = requests.post(
"https://openrouter.ai/api/v1/chat/completions",
headers=headers,
json=payload
)
final_output = final_response.json()["choices"][0]["message"]["content"]
print(final_output) # e.g., "Arquivos: file1.txt, file2.txt"
Passo 7: Lidar com Múltiplas Chamadas de Ferramentas
Se o modelo requer várias chamadas de ferramentas, loop pelo processo:
messages = payload["messages"]
while True:
response = requests.post(
"https://openrouter.ai/api/v1/chat/completions",
headers=headers,
json={"model": "openai/gpt-4", "messages": messages}
)
message = response.json()["choices"][0]["message"]
if "tool_calls" not in message:
print(message["content"])
break
for tool_call in message["tool_calls"]:
function_name = tool_call["function"]["name"]
arguments = json.loads(tool_call["function"]["arguments"])
mcp_response = requests.post(
"http://localhost:8000/call",
json={"name": function_name, "arguments": arguments}
)
tool_result = mcp_response.json()["result"]
messages.extend([
{"role": "assistant", "content": null, "tool_calls": [tool_call]},
{"role": "tool", "tool_call_id": tool_call["id"], "content": json.dumps(tool_result)}
])
Isso garante que todas as chamadas de ferramentas sejam processadas.
Exemplo do Mundo Real: Interação com o Sistema de Arquivos
Vamos aplicar isso a um cenário prático listando arquivos com um Servidor MCP.
- Definição da Ferramenta: Use a ferramenta
list_filesmencionada anteriormente. - Servidor MCP: Suponha que esteja rodando em
http://localhost:8000. - Chamada da API: Envie “Liste os arquivos no diretório atual” para o OpenRouter.
- Manipulação da Resposta: O modelo chama
list_filescom{"path": "."}. - Execução do MCP: O servidor retorna
["file1.txt", "file2.txt"]. - Saída Final: O modelo responde: “Arquivos encontrados: file1.txt, file2.txt.”
Aqui está o código completo:
import requests
import json
headers = {"Authorization": "Bearer your_openrouter_api_key", "Content-Type": "application/json"}
payload = {
"model": "openai/gpt-4",
"messages": [{"role": "user", "content": "Liste os arquivos no diretório atual."}],
"tools": [{
"type": "function",
"function": {
"name": "list_files",
"description": "Lista arquivos em um diretório especificado",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string", "description": "Caminho do diretório"}},
"required": ["path"]
}
}
}]
}
response = requests.post("https://openrouter.ai/api/v1/chat/completions", headers=headers, json=payload)
message = response.json()["choices"][0]["message"]
if "tool_calls" in message:
tool_call = message["tool_calls"][0]
function_name = tool_call["function"]["name"]
arguments = json.loads(tool_call["function"]["arguments"])
mcp_response = requests.post("http://localhost:8000/call", json={"name": function_name, "arguments": arguments})
tool_result = mcp_response.json()["result"]
messages = payload["messages"] + [
{"role": "assistant", "content": null, "tool_calls": [tool_call]},
{"role": "tool", "tool_call_id": tool_call["id"], "content": json.dumps(tool_result)}
]
final_response = requests.post("https://openrouter.ai/api/v1/chat/completions", headers=headers, json={"model": "openai/gpt-4", "messages": messages})
print(final_response.json()["choices"][0]["message"]["content"])
Resolvendo Problemas Comuns
Aqui estão soluções para problemas frequentes:
- Ferramenta Não Chamado: Verifique a sintaxe da definição da ferramenta e a clareza do prompt.
- Argumentos Inválidos: Garanta que os parâmetros correspondam ao JSON Schema.
- Falha do Servidor MCP: Verifique os logs do servidor e o endpoint (
http://localhost:8000/call). - Autenticação da API: Confirme se sua chave do OpenRouter está correta.
Use o Apidog para depurar solicitações e respostas de API de forma eficiente.
Expandindo a Integração
Para exceder 2000 palavras e adicionar profundidade, considere estas extensões:
Exemplo de Consulta ao Banco de Dados
Defina uma ferramenta MCP para consultar um banco de dados:
{
"type": "function",
"function": {
"name": "query_db",
"description": "Consulta um banco de dados com SQL",
"parameters": {
"type": "object",
"properties": {"sql": {"type": "string", "description": "Consulta SQL"}},
"required": ["sql"]
}
}
}
Envie “Obter todos os usuários do banco de dados” para o OpenRouter, processe a chamada query_db e retorne resultados como [{"id": 1, "name": "Alice"}].
Tratamento de Erros
Adicione um tratamento de erros robusto:
try:
mcp_response = requests.post("http://localhost:8000/call", json={"name": function_name, "arguments": arguments})
mcp_response.raise_for_status()
except requests.RequestException as e:
tool_result = f"Erro: {str(e)}"
Isso garante que sua aplicação permaneça estável.
Conclusão
A integrar os Servidores MCP com o OpenRouter permite que sua IA aproveite ferramentas externas através de uma única API. Este guia abordou a configuração, conversão de ferramentas, chamadas de API e exemplos práticos como a interação com o sistema de arquivos. Com benefícios como economia de custos e funcionalidade aprimorada, essa abordagem é uma ótima opção para desenvolvedores técnicos.
Comece a experimentar agora, baixe o Apidog gratuitamente aqui para testar suas APIs. Deixe-me saber como foi!
