{"title":"Construa um cliente MCP customizado","slug":"custom-client","category":"mcp","summary":"Conecte-se ao servidor MCP do Synapse a partir do seu próprio aplicativo usando o SDK MCP.","audience":["human","llm"],"tags":["mcp","custom","sdk","development"],"difficulty":"advanced","updated":"2026-06-27","word_count":177,"read_minutes":1,"lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Construa um cliente MCP customizado\n\nSe você está construindo seu próprio aplicativo LLM, pode se conectar ao\nservidor MCP do Synapse diretamente usando o SDK oficial do MCP. Isso dá ao\nseu app acesso a todas as 79 ferramentas do Synapse.\n\n## SDKs\n\n| Linguagem | Pacote |\n|-----------|--------|\n| TypeScript/JavaScript | `@modelcontextprotocol/sdk` |\n| Python | `mcp` |\n\n## Exemplo em TypeScript\n\n### Instalação\n\n```bash\nnpm install @modelcontextprotocol/sdk\n```\n\n### Conexão via stdio\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\n\nconst transport = new StdioClientTransport({\n command: \"npx\",\n args: [\"-y\", \"synapse-mcp-api@latest\"],\n env: {\n SYNAPSE_MIND_KEY: process.env.SYNAPSE_MIND_KEY!,\n SYNAPSE_URL: \"https://synapse.schaefer.zone\",\n },\n});\n\nconst client = new Client(\n { name: \"my-app\", version: \"1.0.0\" },\n { capabilities: {} }\n);\n\nawait client.connect(transport);\n\n// List all available tools\nconst { tools } = await client.listTools();\nconsole.log(`Available tools: ${tools.length}`);\nfor (const tool of tools) {\n console.log(`- ${tool.name}: ${tool.description}`);\n}\n\n// Call a tool\nconst result = await client.callTool({\n name: \"memory_recall\",\n arguments: {},\n});\nconsole.log(result.content);\n\n// Store a memory\nawait client.callTool({\n name: \"memory_store\",\n arguments: {\n category: \"fact\",\n key: \"custom_client_test\",\n content: \"Built a custom MCP client\",\n tags: [\"test\", \"mcp\"],\n priority: \"normal\",\n },\n});\n\nawait client.close();\n```\n\n### Conexão via HTTP/SSE (remoto)\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { SSEClientTransport } from \"@modelcontextprotocol/sdk/client/sse.js\";\n\nconst transport = new SSEClientTransport(\n new URL(\"https://synapse-mcp.schaefer.zone/sse\"),\n {\n requestInit: {\n headers: {\n Authorization: `Bearer ${process.env.SYNAPSE_MIND_KEY}`,\n },\n },\n }\n);\n\nconst client = new Client(\n { name: \"my-app\", version: \"1.0.0\" },\n { capabilities: {} }\n);\n\nawait client.connect(transport);\n// ... use as above\n```\n\n## Exemplo em Python\n\n### Instalação\n\n```bash\npip install mcp\n```\n\n### Conexão via stdio\n\n```python\nfrom mcp import ClientSession, StdioServerParameters\nfrom mcp.client.stdio import stdio_client\n\nserver_params = StdioServerParameters(\n command=\"npx\",\n args=[\"-y\", \"synapse-mcp-api@latest\"],\n env={\n \"SYNAPSE_MIND_KEY\": \"mk_YOUR_KEY\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\",\n },\n)\n\nasync with stdio_client(server_params) as (read, write):\n async with ClientSession(read, write) as session:\n await session.initialize()\n\n # List tools\n tools = await session.list_tools()\n print(f\"Available tools: {len(tools.tools)}\")\n\n # Call a tool\n result = await session.call_tool(\"memory_recall\", {})\n print(result.content)\n\n # Store a memory\n await session.call_tool(\"memory_store\", {\n \"category\": \"fact\",\n \"key\": \"python_client_test\",\n \"content\": \"Built a Python MCP client\",\n \"tags\": [\"test\", \"mcp\", \"python\"],\n \"priority\": \"normal\",\n })\n```\n\n## Tool Profiles\n\nAo conectar, você pode solicitar um tool profile específico via cabeçalho\n`Mcp-Tool-Profile` (HTTP/SSE) ou env var `MCP_PROFILE` (stdio):\n\n```typescript\n// stdio: set env var\nenv: {\n SYNAPSE_MIND_KEY: \"mk_...\",\n MCP_PROFILE: \"minimal\", // 8 tools instead of 119\n}\n\n// HTTP/SSE: set header\nrequestInit: {\n headers: {\n Authorization: \"Bearer mk_...\",\n \"Mcp-Tool-Profile\": \"minimal\",\n },\n}\n```\n\n## Tratamento de erros\n\n```typescript\ntry {\n const result = await client.callTool({ name: \"memory_recall\", arguments: {} });\n if (result.isError) {\n console.error(\"Tool error:\", result.content);\n } else {\n console.log(\"Success:\", result.content);\n }\n} catch (err) {\n console.error(\"MCP error:\", err);\n}\n```\n\n## Casos de uso\n\n- **Assistentes de IA customizados** — construa seu próprio agente com memória persistente\n- **Automação de workflows** — encadeie ferramentas do Synapse em workflows customizados\n- **Pipelines de dados** — extraia memórias, transforme, carregue em outro lugar\n- **Dashboards de monitoramento** — exiba estatísticas de memória, histórico de chat, tarefas\n\n## Próximos passos\n\n- [Especificação MCP](https://spec.modelcontextprotocol.io)\n- [Repo do Synapse MCP](https://gitlab.com/schaefer-services/synapse-mcp)\n- [Visão geral da API](/docs/api/overview)\n","content_html":"

Construa um cliente MCP customizado

\n

Se você está construindo seu próprio aplicativo LLM, pode se conectar ao\nservidor MCP do Synapse diretamente usando o SDK oficial do MCP. Isso dá ao\nseu app acesso a todas as 79 ferramentas do Synapse.

\n

SDKs

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
LinguagemPacote
TypeScript/JavaScript@modelcontextprotocol/sdk
Pythonmcp
\n

Exemplo em TypeScript

\n

Instalação

\n
npm install @modelcontextprotocol/sdk

Conexão via stdio

\n
import { Client } from "@modelcontextprotocol/sdk/client/index.js";\nimport { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";\n\nconst transport = new StdioClientTransport({\n  command: "npx",\n  args: ["-y", "synapse-mcp-api@latest"],\n  env: {\n    SYNAPSE_MIND_KEY: process.env.SYNAPSE_MIND_KEY!,\n    SYNAPSE_URL: "https://synapse.schaefer.zone",\n  },\n});\n\nconst client = new Client(\n  { name: "my-app", version: "1.0.0" },\n  { capabilities: {} }\n);\n\nawait client.connect(transport);\n\n// List all available tools\nconst { tools } = await client.listTools();\nconsole.log(`Available tools: ${tools.length}`);\nfor (const tool of tools) {\n  console.log(`- ${tool.name}: ${tool.description}`);\n}\n\n// Call a tool\nconst result = await client.callTool({\n  name: "memory_recall",\n  arguments: {},\n});\nconsole.log(result.content);\n\n// Store a memory\nawait client.callTool({\n  name: "memory_store",\n  arguments: {\n    category: "fact",\n    key: "custom_client_test",\n    content: "Built a custom MCP client",\n    tags: ["test", "mcp"],\n    priority: "normal",\n  },\n});\n\nawait client.close();

Conexão via HTTP/SSE (remoto)

\n
import { Client } from "@modelcontextprotocol/sdk/client/index.js";\nimport { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";\n\nconst transport = new SSEClientTransport(\n  new URL("https://synapse-mcp.schaefer.zone/sse"),\n  {\n    requestInit: {\n      headers: {\n        Authorization: `Bearer ${process.env.SYNAPSE_MIND_KEY}`,\n      },\n    },\n  }\n);\n\nconst client = new Client(\n  { name: "my-app", version: "1.0.0" },\n  { capabilities: {} }\n);\n\nawait client.connect(transport);\n// ... use as above

Exemplo em Python

\n

Instalação

\n
pip install mcp

Conexão via stdio

\n
from mcp import ClientSession, StdioServerParameters\nfrom mcp.client.stdio import stdio_client\n\nserver_params = StdioServerParameters(\n    command="npx",\n    args=["-y", "synapse-mcp-api@latest"],\n    env={\n        "SYNAPSE_MIND_KEY": "mk_YOUR_KEY",\n        "SYNAPSE_URL": "https://synapse.schaefer.zone",\n    },\n)\n\nasync with stdio_client(server_params) as (read, write):\n    async with ClientSession(read, write) as session:\n        await session.initialize()\n\n        # List tools\n        tools = await session.list_tools()\n        print(f"Available tools: {len(tools.tools)}")\n\n        # Call a tool\n        result = await session.call_tool("memory_recall", {})\n        print(result.content)\n\n        # Store a memory\n        await session.call_tool("memory_store", {\n            "category": "fact",\n            "key": "python_client_test",\n            "content": "Built a Python MCP client",\n            "tags": ["test", "mcp", "python"],\n            "priority": "normal",\n        })

Tool Profiles

\n

Ao conectar, você pode solicitar um tool profile específico via cabeçalho\nMcp-Tool-Profile (HTTP/SSE) ou env var MCP_PROFILE (stdio):

\n
// stdio: set env var\nenv: {\n  SYNAPSE_MIND_KEY: "mk_...",\n  MCP_PROFILE: "minimal",  // 8 tools instead of 119\n}\n\n// HTTP/SSE: set header\nrequestInit: {\n  headers: {\n    Authorization: "Bearer mk_...",\n    "Mcp-Tool-Profile": "minimal",\n  },\n}

Tratamento de erros

\n
try {\n  const result = await client.callTool({ name: "memory_recall", arguments: {} });\n  if (result.isError) {\n    console.error("Tool error:", result.content);\n  } else {\n    console.log("Success:", result.content);\n  }\n} catch (err) {\n  console.error("MCP error:", err);\n}

Casos de uso

\n\n

Próximos passos

\n\n","urls":{"html":"/docs/mcp/custom-client","text":"/docs/mcp/custom-client?format=text","json":"/docs/mcp/custom-client?format=json","llm":"/docs/mcp/custom-client?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}