Atlantis MCP Server

What is Atlantis MCP Server about?

Atlantis MCP Server is a Python‑driven MCP host that turns ordinary Python functions into discoverable, hot‑reloadable tools. It forms part of a collaborative network where AI agents and developers share capabilities, call each other's functions, and coordinate work without the overhead of constantly updating static tool packages.

How to use Atlantis MCP Server?

1. Clone the repository and navigate to python-server.
2. Create a virtual environment and install Python dependencies.

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

3. Configure the server by editing the runServer script (or copy it to a custom name). Supply your Project Atlantis email and an API key.

   python server.py \
     --email=you@example.com \
     --api-key=foobar \
     --host=localhost \
     --port=8000 \
     --cloud-host=wss://projectatlantis.ai \
     --cloud-port=443 \
     --service-name=home
   

4. Start the MCP client (Lobster) and point it at the server port:

   claude mcp add atlantis_lobster -- npx atlantis-mcp --port 8000
   

   The same works for codex.
5. Add third‑party MCP tools (e.g., OpenWeather) via the dynamic_servers JSON configuration or with a CLI shortcut:

   claude mcp add --transport stdio weather_forecast --env OPENWEATHER_API_KEY=mykey123 \
       -- npx atlantis-open-weather-mcp start-weather-server
   

6. Create or clone dynamic‑function apps under python-server/dynamic_functions/. Functions decorated with @visible become instantly callable tools.
7. Monitor logs in python-server/runServer.log for troubleshooting.

Key Features

• Dynamic Functions – Python functions are auto‑loaded, validated, and hot‑reloaded on file change.
• Dynamic MCP Servers – Third‑party MCP services can be launched from JSON configs or CLI commands.
• Cloud Coordination – Optional Project Atlantis cloud provides central hub for auth, remote discovery, and tool sharing.
• Lobster Client – Lightweight Node‑based MCP client (npx atlantis-mcp) for Claude, Codex, or custom agents.
• Tool Search & Disambiguation – Compound naming (app*function, owner*remote*app*function) resolves conflicts automatically.
• App‑Centric Organization – Folder names become app identifiers; nested apps are supported via slash notation.
• Built‑in Apps – Pre‑installed Chat, Bot, Home, and Setup apps plus a starter Demo app.
• Extensible Architecture – Separate modules for function management, third‑party server handling, and runtime API.

Use Cases

• Bot Development – Build conversational agents that call custom tools (e.g., weather, accounting) without hard‑coded SDKs.
• Cross‑Team Tool Sharing – Teams expose functions as MCP tools that other teams’ agents can discover and invoke.
• Rapid Prototyping – Add or modify a function file; the server hot‑reloads it instantly, allowing fast iteration.
• Distributed Automation – Run multiple remotes with unique service-names; agents can target specific machines via compound names.
• Third‑Party Integration – Plug in existing MCP services (e.g., OpenWeather) via the dynamic_servers folder.

FAQ

Q: Do I need the cloud component? A: No. The server can run completely locally; the cloud only simplifies auth and remote discovery.

Q: Which Python version is required? A: Python 3.13 is recommended for stable async support.

Q: How are secrets handled? A: Set API keys as environment variables (e.g., OPENAI_API_KEY, OPENWEATHER_API_KEY). The server reads them at runtime.

Q: Can I run multiple servers on the same machine? A: Yes. Give each instance a unique --service-name and different ports.

Q: What if a tool call returns “Unknown tool”? A: Check runServer.log for registration errors, ensure the function is in dynamic_functions/ and decorated with @visible.

Q: How do I add a new app without affecting the repository? A: Clone the app’s repository directly into dynamic_functions/. The top‑level folder name becomes the app name and is ignored by the main repo’s .gitignore.

Project Atlantis

Meow! Ideally, you may want to create an account first at www.projectatlantis.ai and then have the bot walk you through setup (assuming everything works okay)

Basically we have a distributed linux-style system that provides tool infra for bots. Tools are arranged in folders for easy management across functions and teams. Teams can call each other's functions directly or of course the bots can just do things themselves. Under the covers is an MCP-compliant system but we support hotloading etc. without some of the clunky overhead of constantly updating MCP tools.

To get started, clone the repo, do the Python env stuff, set up your API keys as environment variables (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.) and connect this local Python server to the main server (see runServer). We give you all the source code to build your own tool-calling chatbot just like Claude or whatever. See Bot/Kitty/ for working examples using OpenRouter and Anthropic APIs — the bot discovers tools dynamically via search rather than pre-loading them.

*note that the @game callback runs whenever a new chat is created

Project Atlantis Network

Each MCP server is part of a collaborative network of AI agents and developers. Using the Model Context Protocol, the platform creates an ecosystem where agents can discover and use each other's capabilities across the network. Tools and functions can be shared, discovered, and coordinated between agents—whether for robot-driven frontier development, automation tasks, or any other application. The network architecture enables agents to find and leverage tools from other users, creating a decentralized ecosystem of shared capabilities.

The centerpiece of this project is a Python MCP host (referred to as a 'remote') that lets you install functions and 3rd party MCP tools on the fly

Quick Start

1. Prerequisites - need to install Python for the server and Node for Lobster (the MCP client); you should also install uv/uvx and node/npx since it seems that MCP needs both

2. Python 3.13 seems to be most stable right now because of async support

3. Set up your Python virtual environment and install dependencies:

cd python-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. Edit the runServer script in the python-server folder and set the email and service name (it's actually best practice to create a copy "runServerFoo" that you can replace the runServer file with when we do updates):

python server.py  \
  --email=youremail@gmail.com  \             # email you use for project atlantis
  --api-key=foobar \                         # should change online
  --host=localhost \                         # npx MCP will be looking here to connect to remote (assumes there is at least one running locally)
  --port=8000  \
  --cloud-host=wss://projectatlantis.ai  \   # points to cloud
  --cloud-port=443  \
  --service-name=home                        # remote name, can be anything but must be unique across all machines

5. The MCP client is now called Lobster. Use the port configured by --port in the Python server's launch command (for example, your runServer script). Replace YOUR_SERVER_PORT below with that number; do not assume it is 8000.

To connect it to Claude Code:

claude mcp add atlantis_lobster -- npx atlantis-mcp --port YOUR_SERVER_PORT

To connect to Codex:

codex mcp add atlantis_lobster -- npx atlantis-mcp --port YOUR_SERVER_PORT

The default port is 8000 only when no port override is configured. If you change the server port, update the MCP entry's --port argument too. See the Lobster client README for a JSON configuration template.

To add Atlantis Open Weather for testing:

claude mcp add --transport stdio weather_forecast --env OPENWEATHER_API_KEY=mykey123 -- uvx --from atlantis-open-weather-mcp start-weather-server

6. To connect to Atlantis, sign into https://www.projectatlantis.ai under the same email

7. Your remote(s) should autoconnect using email and default api key = 'foobar' (see 'api' command to generate a new key later). The first server to connect will be assigned your 'default' unless you manually change it later

8. Chat comes pre-installed, along with the Home, Bot and Setup apps, in python-server/dynamic_functions/. On first run, the server also creates a starter Demo app with example functions. No separate installation is needed for these bundled apps. The dynamic_servers/ folder includes an example weather config.

9. You can run this standalone MCP or accessed from the cloud or both

Architecture

Caveat: MCP terminology is already terrible and calling things 'servers' or 'hosts' just makes it more confusing because MCP is inherently p2p

Pieces of the system:

• Cloud: our experimental Atlantis cloud server; mostly a place to share tools and let users bang on them
• Remote: the Python server process found in this repo, officially referred to as an MCP 'host' (you can run >1 either on same box or on different one, just specify different service names)
• Dynamic Function: a simple Python function that you write, acts as a tool
• Dynamic MCP Server: any 3rd party MCP, stored as a JSON config file

Note that MCP auth and security are still being worked out so using the cloud for auth is easier right now

Directories

1. Python Remote (MCP P2P server) (python-server/)

   • Location of our 'remote'. Runs locally but can be controlled remotely

2. Lobster (MCP Client) (client/)

   • lets Claude Code or Codex run Atlantis commands or chat via MCP
   • uses npx (easy to install into Claude Code or Codex)
   • cloud connection not needed - although it may complain
   • only supports a subset of the spec
   • can only see tools on the local box (at least right now) or shared tools set to 'public'

Python Server Layout

Start in python-server/server.py. It is the protocol host: it owns the WebSocket and cloud connections, and MCP tools/call goes through DynamicAdditionServer._handle_tools_call(). From there:

• DynamicFunctionManager.py loads, validates and calls the Python tools in dynamic_functions/, and defines the decorators.
• DynamicServerManager.py runs the third-party MCP servers configured in dynamic_servers/.
• atlantis.py is the runtime API that tool code calls back into.
• lobster.py holds the local Lobster client's readme / command / chat tools.
• state.py and utils.py hold config, logging and shared helpers.

Further docs:

• Dynamic Functions: writing tools.
• atlantis API: the runtime, including browser callbacks.
• Security Model: auth and trust boundaries.

Features

Dynamic Functions

Dynamic functions give users the ability to create and maintain custom functions-as-tools. Functions are loaded on start and automatically reloaded when modified.

The python-server/dynamic_functions/ directory includes the pre-installed Chat, Bot, Home, and Setup apps. These apps are tracked with the server source. Seeing them on a new server is expected.

On first run, the server also creates a starter Demo app with example functions, once per .demo_scaffolded marker. Everything else under dynamic_functions/ is ignored by this repository.

Add your own app in a new subfolder. To keep an app in its own repository, clone that repository directly into dynamic_functions/:

cd python-server/dynamic_functions
git clone git@gitlab.com:you/my-atlantis-app.git MyApp

The app folder is its own Git repository, and the server repository ignores it. Keep the bundled folders in place; do not replace the entire dynamic_functions/ directory.

For detailed information about creating and using dynamic functions, see the Dynamic Functions Documentation.

Dynamic MCP Servers

• gives users the ability to install and manage third-party MCP server tools; JSON config files are kept in the dynamic_servers/ folder

• each MCP server will need to be 'started' first to fetch the list of tools

• each server config follows the usual JSON structure that contains an 'mcpServers' element; for example, this installs an openweather MCP server:

  {
     "mcpServers": {
        "openweather": {
           "command": "uvx",
           "args": [
           "--from",
           "atlantis-open-weather-mcp",
           "start-weather-server",
           "--api-key",
           "<your openweather api key>"
           ]
        }
     }
  }
  

The weather MCP service is just an existing one I ported to uvx. See here

Cloud

The cloud service at https://www.projectatlantis.ai provides a centralized hub for managing your remote servers and sharing tools across machines.

App Organization

Dynamic functions are organized into apps using folder structure. Simply place your .py files in subdirectories:

dynamic_functions/
├── Home/                    # App: "Home"
│   └── kitty.py
├── Accounting/              # App: "Accounting"
│   ├── accounting.py
│   └── foo.py
└── FilmFromImage/          # App: "FilmFromImage"
    └── qwen_image_edit_local.py

The folder name IS the app name. Functions in Home folder are assigned accordingly.

Nested Apps (Subfolders)

Create nested app structures using subfolders:

dynamic_functions/
└── MyApp/
    └── SubModule/
        └── Feature/
            └── my_function.py

This creates the app name: MyApp/SubModule/Feature

Best Practices:

• Keep it simple - one level of folders is usually enough
• Use descriptive folder names (e.g., Chat, Admin, Tools)
• Group related functions together in the same folder
• The folder structure keeps your code organized and clear

Tool Calling with Search Terms

When calling tools, you can use compound tool names to disambiguate functions. Only include as much of the path as needed to uniquely identify the function.

Format: remote_owner*remote_name*app*location*function

Key Principle: Use the simplest form that resolves uniquely

# If you have these functions:
# - dynamic_functions/Chat/send_message.py
# - dynamic_functions/Email/send_message.py
# - dynamic_functions/SMS/send_message.py

send_message              ❌ Ambiguous! Which one?
**Chat**send_message      ✅ Clear! The one in Chat
**Email**send_message     ✅ Clear! The one in Email

Examples:

update_image                          → Simple call (only works if unique)
**MyApp**update_image                 → Specify app to disambiguate
**MyApp/SubModule**process_data       → Nested app path
alice*prod*Admin**restart             → Full routing: owner + remote + app + function
***office*print                       → Just location context

How it works:

• Fields: remote_owner*remote_name*app*location*function
• Separate fields with * (asterisk)
• Omit fields you don't need (use empty strings: **App**func)
• The app field supports slash notation for nested apps (MyApp/SubModule)
• The last field is always the function name
• No asterisks = treat entire name as function name

When to use compound names:

• Name conflicts: Multiple apps have functions with the same name
• Remote targeting: Call functions on specific remotes from the cloud
• Location routing: Target functions at specific physical locations
• Multi-user setups: Specify owner and remote in shared environments

Best practice: Start simple (update_image) and add context only when needed to resolve ambiguity (**ImageTools**update_image).

Example:

# File: dynamic_functions/ImageTools/process.py
@visible
async def update_image(image_path: str):
    """Update an image."""
    return "updated"

# If this is the ONLY update_image:
update_image                          ✅ Works fine!

# If Chat app ALSO has update_image:
**ImageTools**update_image            ✅ Now we need to specify the app

Bot Runtime

The bot/chat runtime lives in this repo as a dynamic-functions app:

python-server/dynamic_functions/Chat/

It holds the game/chat tools, bot runtime, static content under Game/, and live player state under Data/. The Atlantis MCP server treats it like any other dynamic-functions app: it scans the folder, exposes decorated functions as tools, and reloads them when files change.

Key Files

• python-server/dynamic_functions/Home/ — small platform-owned Home app used for Lobster/Multix readme entry points and the file callback. See the Home README.
• python-server/dynamic_functions/Chat/ — the bot/chat runtime app. See the Chat README.
• python-server/dynamic_functions/Terrain/ — terrain tooling, kept in its own private repository (git@gitlab.com:project_atlantis/terrain.git) and cloned into this folder. Not tracked here.
• python-server/dynamic_functions/Chat/Game/ — static game content: locations, scenes. Tracked.
• python-server/dynamic_functions/Bot/ — static bot info under Bot/<sid>/ (config, prompt, image). Tracked. Kept separate from Chat so bots can live on a different machine than the game.
• python-server/dynamic_functions/Chat/Data/ — live per-game state, keyed by game_key. Not tracked.

Troubleshooting

If MCP tools aren't working (e.g. returning Unknown tool errors), check the server log first. The Python server writes detailed logs to python-server/runServer.log — this file shows exactly what's happening with tool calls, cloud auth, and client connections. It can get large, so tail the last ~1000 lines:

tail -1000 python-server/runServer.log

Common issues visible in the log:

• ⚠️ Unexpected tool call from local client — the server received a tool call but didn't recognize it; check that your tools are registered
• ❌ Authentication failed — cloud credentials are wrong or the account doesn't exist; check your email/api-key
• 🏠 Local MCP tool call intercepted — confirms the server is receiving tool calls from the MCP client
• MCP handshake errors usually mean the client is pointed at the wrong port. The default local MCP port is 8000; make sure the server --port and client --port match.

Visitor-related log lines include "Visitor:", "New conversation for", and "Injected time-gap message".

Our Greenland Terrain Server

The goal is to use this system as the main bot infrastructure (tool etc.) for our Greenland terrain server