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

# Model Context Protocol (MCP)

> Understanding MCP and why Noorle uses it for tool standardization

The **Model Context Protocol (MCP)** is an open standard that defines how AI models and agents can discover and use tools. Noorle uses MCP as its foundational protocol for exposing capabilities.

## What is MCP?

MCP is a specification developed by Anthropic that standardizes the interface between AI models and tools. Instead of each AI provider or tool implementing their own integration formats, MCP provides a unified language.

**Think of it like HTTP for AI tools.**

* HTTP: Standardized how web clients talk to servers
* MCP: Standardizes how AI agents discover and invoke tools

## Why MCP Matters

### Before MCP

```mermaid theme={null}
graph LR
    Agent["AI Agent<br/>Needs schema<br/>Custom parser<br/>Unique errors<br/>No discovery"]
    Tools["Tools<br/>Each a snowflake"]
    Agent -.->|Complex integration| Tools
```

### With MCP

```mermaid theme={null}
graph LR
    Agent["AI Agent"]
    Protocol["MCP Protocol<br/>Standard interface"]
    Tools["Tools<br/>Standard interface"]
    Agent -->|Standard| Protocol
    Protocol -->|Standard| Tools
```

Now:

* Agents use **one unified interface** for all tools
* New tools are discovered automatically
* Error handling is consistent
* Tools can be swapped without agent changes

## MCP Primitives

MCP defines three core primitives that tools expose:

### 1. Tools

Callable functions with typed inputs and outputs.

```json theme={null}
{
  "name": "search_github",
  "description": "Search GitHub repositories",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "language": {
        "type": "string",
        "description": "Programming language filter (optional)"
      }
    },
    "required": ["query"]
  }
}
```

**Key aspects:**

* **Name**: MCP-compatible identifier (alphanumeric + underscore)
* **Description**: Human-readable purpose
* **Input Schema**: JSON Schema defining what parameters it accepts
* **Output**: Structured response (JSON)

### 2. Resources

Read-only data that tools can reference.

```json theme={null}
{
  "uri": "memory://conversation-history",
  "name": "Conversation History",
  "description": "Current conversation with user",
  "mimeType": "text/plain"
}
```

**Use cases:**

* Conversation memory
* Document references
* Configuration data
* Read-only knowledge bases

### 3. Prompts

Reusable prompt templates that guide model behavior.

```json theme={null}
{
  "name": "analyze-sentiment",
  "description": "Analyze sentiment of user message",
  "arguments": [
    {
      "name": "text",
      "description": "Text to analyze"
    }
  ]
}
```

**Benefits:**

* Standardize prompt engineering across tools
* Document best practices for tool usage
* Enable tool-specific optimization hints

## How Noorle Uses MCP

Noorle exposes all capabilities (builtin, plugin, connector) through MCP:

```mermaid theme={null}
graph TD
    GW["Noorle MCP Gateway<br/>mcp-{id}.noorle.com"]

    GW --> Tools["Tools"]
    Tools --> T1["files_read<br/>Built-in"]
    Tools --> T2["web_search<br/>Built-in"]
    Tools --> T3["http_post<br/>Built-in"]
    Tools --> T4["code_run<br/>Built-in"]
    Tools --> T5["knowledge_search<br/>Built-in"]
    Tools --> T6["my_custom_analyzer<br/>Plugin"]
    Tools --> T7["shopify_orders<br/>Connector"]
    Tools --> T8["stripe_charges<br/>Connector"]

    GW --> Resources["Resources"]
    Resources --> R1["session://memory<br/>Conversation context"]
    Resources --> R2["kb://docs<br/>Knowledge base"]

    GW --> Prompts["Prompts"]
    Prompts --> P1["system-prompt<br/>Agent behavior"]
    Prompts --> P2["tool-hints<br/>Tool-specific guidance"]
```

## MCP Transport

MCP is transport-agnostic. Noorle supports:

### Server-Sent Events (SSE)

Recommended for **web clients and long-lived connections**.

```mermaid theme={null}
graph LR
    Client["Client HTTP GET /sse"]
    Stream["Streams: data: {jsonrpc: 2.0, ...}"]
    Persist["Persistent connection<br/>for tool calls"]

    Client --> Stream
    Stream --> Persist
```

**Advantages:**

* Native HTTP/REST
* Works through proxies and load balancers
* Browser-compatible
* Simpler than WebSocket

### HTTP Long-Polling

Fallback for **restricted networks**.

```mermaid theme={null}
graph LR
    C1["Client polls<br/>GET /poll?seq=123"]
    C2["Returns:<br/>{messages: [...]}"]
    C3["Client polls again<br/>in 2 seconds"]

    C1 --> C2
    C2 --> C3
```

**Advantages:**

* Works in highly restricted environments
* No special proxying needed

Noorle uses **SSE by default** with **long-polling fallback** for maximum compatibility.

## Tool Discovery via MCP

When a client connects to an MCP gateway, it discovers available tools:

```javascript theme={null}
const gateway = new NoorleMcpClient({
  url: "https://mcp-{id}.noorle.com",
  auth: { token: "jwt-token" }
});

// List all tools
const tools = await gateway.listTools();

// Response
[
  {
    name: "web_search",
    description: "Search the web with Bing",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string" }
      },
      required: ["query"]
    }
  },
  // ... more tools
]
```

## Tool Invocation via MCP

Once discovered, tools are called through a standard interface:

```javascript theme={null}
const result = await gateway.callTool("web_search", {
  query: "latest AI trends"
});

// Response
{
  "success": true,
  "data": {
    "results": [
      {
        "title": "...",
        "url": "...",
        "snippet": "..."
      }
    ]
  }
}
```

## MCP vs REST APIs

| Aspect             | MCP                      | REST API                       |
| ------------------ | ------------------------ | ------------------------------ |
| **Discovery**      | Automatic (`listTools`)  | Manual reading docs            |
| **Schema**         | Standardized JSON Schema | Each API different             |
| **Error Handling** | Consistent format        | API-specific                   |
| **Authentication** | JWT or API key           | Various (OAuth, API key, etc.) |
| **Streaming**      | First-class support      | Add-on (webhooks, polling)     |

**TL;DR:** MCP is REST for AI tools.

## MCP Ecosystem

Noorle is part of the broader MCP ecosystem:

* **MCP Servers**: Tools that expose capabilities (Noorle, Anthropic plugins, community servers)
* **MCP Clients**: AI agents that consume tools (Claude, custom agents, integrations)
* **MCP Registry**: Directory of public servers ([https://mcp-registry.io](https://mcp-registry.io))

```mermaid theme={null}
graph LR
    subgraph Clients["MCP Clients<br/>AI Agent"]
        C1["Claude"]
        C2["Custom Agent"]
        C3["Integration"]
    end

    subgraph Servers["MCP Servers<br/>Tool Provider"]
        S1["Noorle Gateway"]
        S2["Slack Bot"]
        S3["GitHub MCP"]
    end

    C1 ←-->|MCP| S1
    C2 ←-->|MCP| S2
    C3 ←-->|MCP| S3
```

## Omni Tool: Smart Tool Discovery

Rather than listing 50+ tools and expecting the AI to choose, Noorle's **Omni Tool** uses AI to discover the right tool:

```mermaid theme={null}
graph TD
    A["User: Find me the<br/>top-performing product in Q4"]
    B["Omni Tool: Analyzing request...<br/>I need the shopify_orders tool"]
    C["Execution: Calls shopify_orders<br/>with date range Q4"]
    D["Result: Returns product<br/>performance data"]

    A --> B
    B --> C
    C --> D
```

The agent says "find top product" once, and Omni Tool maps that to the right tool automatically.

See [Omni Tool](/docs/learn/concepts/omni-tool) for details.

## Key Takeaways

* **MCP is the standard** for AI tool integration
* **Noorle uses MCP** to expose all capabilities uniformly
* **No tool lock-in**: Your tools work with any MCP client
* **Automatic discovery**: Clients learn available tools on connection
* **Consistent interface**: All tools follow same pattern regardless of type

## Next: Gateways

Now that you understand MCP, see how [MCP Gateways](/docs/learn/concepts/mcp-gateways) expose these tools to clients.