From 5b408d7873b8a99cb5826a242a61ba127fd8a52d Mon Sep 17 00:00:00 2001 From: Abhinav Mathur Date: Thu, 19 Jun 2025 18:12:49 +0530 Subject: [PATCH 1/4] added deployment readme --- README.md | 4 +++ deployment/Readme.md | 58 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 deployment/Readme.md diff --git a/README.md b/README.md index 6333781..f3c0ee6 100644 --- a/README.md +++ b/README.md @@ -48,3 +48,7 @@ We welcome contributions to the Atlan Agent Toolkit! Please follow these guideli 6. **Documentation:** - Update documentation to reflect your changes. - Add comments to your code where necessary. + +## Deployment + +For information on running the server in different environments (stdio, SSE, or streamable HTTP), see the [deployment guide](deployment/Readme.md). diff --git a/deployment/Readme.md b/deployment/Readme.md new file mode 100644 index 0000000..3428c4f --- /dev/null +++ b/deployment/Readme.md @@ -0,0 +1,58 @@ +## Deployment Guide for Atlan MCP Server + +This document explains the various ways you can start the **Atlan MCP Server** and when to choose a given transport mechanism. + +### Quick-start + +```bash +# Default (stdio – recommended for local development) +python modelcontextprotocol/server.py + +# Stream over Server-Sent Events (SSE) – great for browsers or reverse proxies +python modelcontextprotocol/server.py --transport sse --host 0.0.0.0 --port 8000 + +# Stream over plain HTTP ("streamable-http") – useful when SSE is not available +python modelcontextprotocol/server.py --transport streamable-http --host 0.0.0.0 --port 8000 --path / +``` + +### Transport options + +- **`stdio` (default)** + Communicates over standard input/output. + • Benefits: Zero network overhead; perfect for running the agent as a local subprocess. + • When to use: Local development or when integrating directly with parent processes or editors that spawn the server. + +- **`sse`** + Uses **Server-Sent Events** over HTTP—the server keeps an HTTP connection open and pushes a `text/event-stream` as new data arrives. + • Benefits: Built-in support in modern browsers & many HTTP reverse proxies; uni-directional and firewall-friendly; low-latency streaming suited for real-time UI updates. + • When to use: When you are building a Web UI that consumes streamed completions, or you want a push-based model but do not need the bi-directionality of WebSockets. + +- **`streamable-http`** + Sends a standard HTTP response whose body is streamed incrementally (chunked transfer-encoding). + • Benefits: Works with any HTTP client (curl, Python `requests`, Java `HttpClient`, etc.); no special SSE handling required; plays nicely with infrastructure that terminates or transforms HTTP but does **not** understand event streams. + • When to use: The consumer is a language or runtime lacking SSE support, or you want to keep the transport strictly within the HTTP spec without custom headers. + +> **Note** +> The CLI flag is `--transport streamable-http` (with a hyphen), while you may see it described conceptually as *HTTP-streamable*. + +### Choosing between **SSE** and **streamable-HTTP** + +Both transports let you receive incremental updates over the network. The table below can help you decide: + +| Criterion | Choose **SSE** if… | Choose **streamable-HTTP** if… | +|-----------|-------------------|------------------------------| +| Client library availability | Your consumer is a browser or a library that natively understands `text/event-stream`. | You only have a basic HTTP client that can read a stream of bytes/chunks. | +| Proxy / Load-balancer support | You have control over proxy settings and can enable event-stream passthrough. | You are behind a gateway that **rewrites** or **buffers** SSE but still supports chunked HTTP responses. | +| Simplicity of parsing | You prefer the simple event structure (`data: ...\n\n`). | You prefer raw JSON or text chunks without the SSE framing. | +| Bi-directionality | Not required. | Not required. *(If you need full duplex, consider WebSockets—currently not exposed by the server.)* | + +### Environment variables & production tips + +* Ensure `ATLAN_BASE_URL` and `ATLAN_API_KEY` are provided (e.g., via a secrets manager). +* Expose the chosen port (`--port`, default `8000`) in your container or deployment manifest. +* Use health checks (e.g., `GET /healthz`) if you add one via a reverse proxy. +* Pin the server image/tag that matches the library versions required by your agent. + +--- + +For additional configuration (timeouts, logging, etc.) refer to `modelcontextprotocol/settings.py` and the root `README.md`. From 44bd355c548c05a3d3e85fc9a70b4a3fb6411ae7 Mon Sep 17 00:00:00 2001 From: Abhinav Mathur Date: Fri, 20 Jun 2025 12:24:17 +0530 Subject: [PATCH 2/4] fix checks --- deployment/Readme.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/deployment/Readme.md b/deployment/Readme.md index 3428c4f..338052d 100644 --- a/deployment/Readme.md +++ b/deployment/Readme.md @@ -17,22 +17,22 @@ python modelcontextprotocol/server.py --transport streamable-http --host 0.0.0.0 ### Transport options -- **`stdio` (default)** - Communicates over standard input/output. - • Benefits: Zero network overhead; perfect for running the agent as a local subprocess. +- **`stdio` (default)** + Communicates over standard input/output. + • Benefits: Zero network overhead; perfect for running the agent as a local subprocess. • When to use: Local development or when integrating directly with parent processes or editors that spawn the server. -- **`sse`** - Uses **Server-Sent Events** over HTTP—the server keeps an HTTP connection open and pushes a `text/event-stream` as new data arrives. - • Benefits: Built-in support in modern browsers & many HTTP reverse proxies; uni-directional and firewall-friendly; low-latency streaming suited for real-time UI updates. +- **`sse`** + Uses **Server-Sent Events** over HTTP—the server keeps an HTTP connection open and pushes a `text/event-stream` as new data arrives. + • Benefits: Built-in support in modern browsers & many HTTP reverse proxies; uni-directional and firewall-friendly; low-latency streaming suited for real-time UI updates. • When to use: When you are building a Web UI that consumes streamed completions, or you want a push-based model but do not need the bi-directionality of WebSockets. -- **`streamable-http`** - Sends a standard HTTP response whose body is streamed incrementally (chunked transfer-encoding). - • Benefits: Works with any HTTP client (curl, Python `requests`, Java `HttpClient`, etc.); no special SSE handling required; plays nicely with infrastructure that terminates or transforms HTTP but does **not** understand event streams. +- **`streamable-http`** + Sends a standard HTTP response whose body is streamed incrementally (chunked transfer-encoding). + • Benefits: Works with any HTTP client (curl, Python `requests`, Java `HttpClient`, etc.); no special SSE handling required; plays nicely with infrastructure that terminates or transforms HTTP but does **not** understand event streams. • When to use: The consumer is a language or runtime lacking SSE support, or you want to keep the transport strictly within the HTTP spec without custom headers. -> **Note** +> **Note** > The CLI flag is `--transport streamable-http` (with a hyphen), while you may see it described conceptually as *HTTP-streamable*. ### Choosing between **SSE** and **streamable-HTTP** From 70501b51a7bfeb94a8b3fa41a2850af1e15f056c Mon Sep 17 00:00:00 2001 From: Abhinav Mathur Date: Tue, 24 Jun 2025 15:01:29 +0530 Subject: [PATCH 3/4] updated deployment section --- README.md | 4 ---- modelcontextprotocol/README.md | 5 +++++ 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f3c0ee6..6333781 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,3 @@ We welcome contributions to the Atlan Agent Toolkit! Please follow these guideli 6. **Documentation:** - Update documentation to reflect your changes. - Add comments to your code where necessary. - -## Deployment - -For information on running the server in different environments (stdio, SSE, or streamable HTTP), see the [deployment guide](deployment/Readme.md). diff --git a/modelcontextprotocol/README.md b/modelcontextprotocol/README.md index 8869c8d..3897dbf 100644 --- a/modelcontextprotocol/README.md +++ b/modelcontextprotocol/README.md @@ -15,6 +15,7 @@ The Atlan [Model Context Protocol](https://modelcontextprotocol.io/introduction) - [MCP configurations](#mcp-configurations) - [Python (Local)](#python-local) - [Container (Local)](#container-local) +- [Deployment](#deployment) - [Production Deployment](#production-deployment) - [MCP configuration](#mcp-configuration) - [Develop Locally](#develop-locally) @@ -182,6 +183,10 @@ docker build . -t atlan-mcp-server:latest - Make sure to replace `your_api_key`, `your_instance`, and `your_agent_id` with your actual Atlan API key, instance URL, and agent ID(optional) respectively +## Deployment + +For information on running the server in different environments (stdio, SSE, or streamable HTTP), see the [deployment guide](../deployment/Readme.md). + ## Production Deployment - Host the Atlan MCP container image on the cloud/platform of your choice - Make sure you add all the required environment variables From facb2e9486b2965c20f07879ed0f1c6a77697096 Mon Sep 17 00:00:00 2001 From: Abhinav Mathur Date: Mon, 7 Jul 2025 18:39:10 +0530 Subject: [PATCH 4/4] Update and rename Readme.md to README.md --- deployment/{Readme.md => README.md} | 12 ------------ 1 file changed, 12 deletions(-) rename deployment/{Readme.md => README.md} (67%) diff --git a/deployment/Readme.md b/deployment/README.md similarity index 67% rename from deployment/Readme.md rename to deployment/README.md index 338052d..53444b6 100644 --- a/deployment/Readme.md +++ b/deployment/README.md @@ -35,23 +35,11 @@ python modelcontextprotocol/server.py --transport streamable-http --host 0.0.0.0 > **Note** > The CLI flag is `--transport streamable-http` (with a hyphen), while you may see it described conceptually as *HTTP-streamable*. -### Choosing between **SSE** and **streamable-HTTP** - -Both transports let you receive incremental updates over the network. The table below can help you decide: - -| Criterion | Choose **SSE** if… | Choose **streamable-HTTP** if… | -|-----------|-------------------|------------------------------| -| Client library availability | Your consumer is a browser or a library that natively understands `text/event-stream`. | You only have a basic HTTP client that can read a stream of bytes/chunks. | -| Proxy / Load-balancer support | You have control over proxy settings and can enable event-stream passthrough. | You are behind a gateway that **rewrites** or **buffers** SSE but still supports chunked HTTP responses. | -| Simplicity of parsing | You prefer the simple event structure (`data: ...\n\n`). | You prefer raw JSON or text chunks without the SSE framing. | -| Bi-directionality | Not required. | Not required. *(If you need full duplex, consider WebSockets—currently not exposed by the server.)* | ### Environment variables & production tips * Ensure `ATLAN_BASE_URL` and `ATLAN_API_KEY` are provided (e.g., via a secrets manager). * Expose the chosen port (`--port`, default `8000`) in your container or deployment manifest. -* Use health checks (e.g., `GET /healthz`) if you add one via a reverse proxy. -* Pin the server image/tag that matches the library versions required by your agent. ---