> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neosantara.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP & Agent Architecture

> Understand the difference between MCP Gateway (Server) and MCP Connector (Client) in Neosantara.

Neosantara implements the Model Context Protocol (MCP) in two distinct roles: as an **MCP Gateway (Server)** providing tools to local IDEs and agents, and as an **MCP Connector (Client)** connecting AI models to your remote MCP servers.

```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
flowchart TD
    subgraph Mode1["1. MCP Gateway (Neosantara as Server)"]
        direction TB
        C1["IDEs & Coding Clients<br/>(Cursor, Claude Code, Cline, Claude Desktop)"]
        G1["Neosantara MCP Gateway<br/>/v1/mcp"]
        subgraph Tools1["Built-in Neosantara Tools"]
            direction LR
            T1["chat<br/>(Responses API)"]
            T2["list-models<br/>(Catalog & Status)"]
            T3["generate-image<br/>(Image Generation)"]
            T4["list-image-models"]
        end
        C1 -->|"SSE / HTTP<br/>Header: x-api-key: nsk_mcp_..."| G1
        G1 --> T1
        G1 --> T2
        G1 --> T3
        G1 --> T4
    end

    subgraph Mode2["2. MCP Connector (Neosantara as Client)"]
        direction TB
        App2["Your Application or Agent"]
        G2["Neosantara Gateway<br/>/v1/chat/completions<br/>(SSRF Protected)"]
        Remote2["Your Remote MCP Servers<br/>(GitHub, Database, Slack, CRM)"]
        App2 -->|"Chat Payload<br/>mcp_servers: [...]"| G2
        G2 <-->|"Outbound HTTPS / SSE"| Remote2
    end
```

## Comparing the Two MCP Roles

| Criteria | MCP Gateway (Server) | MCP Connector (Client) |
| :- | :- | :- |
| **Neosantara Role** | Tool Provider (Server) | Tool Consumer (Client) |
| **Endpoint** | `https://api.neosantara.xyz/v1/mcp` | `https://api.neosantara.xyz/v1/chat/completions` |
| **Auth Format** | Dedicated MCP key (`nsk_mcp_...`) | Standard Gateway API key (`nsk_...`) |
| **Primary Audience** | Coding IDEs, CLI agents, Claude Desktop | Backend applications, autonomous bots, agent pipelines |
| **Operation** | External client invokes Neosantara built-in tools | Gateway invokes your MCP servers during model inference |
| **Protocol** | SSE or Streamable HTTP JSON-RPC | Outbound Streamable HTTP and SSE with SSRF protection |

## When to Use Each Mode

### Use MCP Gateway When:

* You want to connect coding IDEs (Cursor, Windsurf) or Claude Desktop to Neosantara AI capabilities.
* You need tools such as image generation or model catalog discovery directly from an IDE chat window.
* You configure CLI agents such as Claude Code to call Neosantara tools.

### Use MCP Connector When:

* You build applications where LLMs need access to private databases, internal APIs, or third-party services through your own MCP servers.
* You want to avoid writing client-side tool-calling orchestration loops. Simply provide your MCP server URLs, and Neosantara handles tool discovery, execution, and response synthesis automatically.

## Related Guides

> [card] [MCP Connector](https://docs.neosantara.xyz/en/agents/mcp-connector.md)
>
> Connect chat models to your remote MCP servers automatically.

> [card] [MCP API Keys](https://docs.neosantara.xyz/en/agents/mcp-keys.md)
>
> nsk\_mcp\_ key format, tier rate limits, and creation instructions.

> [card] [Coding Agents & IDEs](https://docs.neosantara.xyz/en/agents/claude-code.md)
>
> Setup guides for Claude Code, OpenCode, Cursor, and Cline.

> [card] [Claude Desktop](https://docs.neosantara.xyz/en/agents/claude-desktop.md)
>
> Configure Claude Desktop application with Neosantara SSE transport.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.