mammoth-mcp-server

The Mammoth MCP server. An AI client (Claude, ChatGPT) uses its tools to explore, clean, transform and export data in Mammoth, as the signed-in user.

The server depends on one Mammoth package: the SDK (mammoth-io). Every tool reaches Mammoth through the API, as the SDK does. The server imports no backend code.

Layout

Settings

Sign-in

This server signs nobody in. Mammoth's own authorization server does: the OAuth server the Mammoth API serves. This server is an OAuth resource server only.

1. A client calls /mcp with no token. The server answers 401 and points to /.well-known/oauth-protected-resource/mcp.
2. That document names Mammoth's authorization server (MAMMOTH_OAUTH_URL). The client reads the server's metadata there and sends the user to it.
3. The user signs in to Mammoth, picks a workspace and a project, and approves. The client asks for a token for this server's URI, <MCP_SERVER_URL>/mcp (the resource parameter, RFC 8707).
4. The client calls /mcp with that token. On every request the server asks Mammoth what the token is for (GET /workspaces/current). The server takes the token only when Mammoth says it is live and was issued for this server's URI.
5. Each tool call goes to the Mammoth API with the same token, so the user's permissions apply.

A token belongs to one workspace. A tool call for another workspace is refused. A Mammoth API token made by hand in Workspace settings was issued for no server, so this server refuses it.

The server keeps no sign-in and no token, with one exception: an upload link holds the caller's token, sealed, in Redis until the user uploads or 30 minutes pass.

What Mammoth needs

• The MCP server's URI, <MCP_SERVER_URL>/mcp, in mvc-service const.ini, section [oauth], key MCP_RESOURCES. Mammoth issues a token for no other resource.
• GET /workspaces/current must return the token's resource beside the workspace id. Without it this server refuses every token.

Before it works in an environment below lists every step, in the order to check them.

Run

As a container, which needs nothing on the host but Docker

The image is built from this repository, so a deployment never waits for a release of the SDK. Build it from the repository root, which is the build context:

cp mammoth-mcp-server/deploy/.dockerignore.example .dockerignore
docker build -f mammoth-mcp-server/deploy/Dockerfile -t mammoth-mcp-server .
docker run --env-file mammoth-mcp-server/deploy/.env -p 8270:8270 mammoth-mcp-server

With a Redis of its own, as one stack:

cp mammoth-mcp-server/.env.example mammoth-mcp-server/deploy/.env   # then set the values
docker compose -f mammoth-mcp-server/deploy/compose.yaml up -d --build

The server keeps nothing in memory between requests, so it scales by adding containers. They share only Redis.

From a virtual environment

pip install mammoth-mcp-server
cp .env.example .env        # then set the values
mammoth-mcp-server          # or: uvicorn mammoth_mcp_server.app:create_app --factory

What deploy/ holds

Before it works in an environment

Each of these stops the sign-in on its own, so check them in order.

1. DNS and the front door point MCP_SERVER_URL at the server's port. deploy/nginx.example.conf holds the server block.

2. MCP_ENCRYPTION_KEY is set. It is the only secret this server keeps. Nothing else is required that has no default; see Settings.

3. Mammoth knows this server: MCP_RESOURCES = <MCP_SERVER_URL>/mcp, in mvc-service const.ini, section [oauth]. Mammoth issues a token for no other resource.

4. The Mammoth host serves its OAuth metadata where a client looks for it. For an issuer with a path, RFC 8414 puts the document at /.well-known/oauth-authorization-server/api/v2, and apiv2 serves it at its own path, so the front door has to join the two. The second server block in deploy/nginx.example.conf does it. Check it with:

   curl https://<mammoth host>/.well-known/oauth-authorization-server/api/v2
   

   It must answer the document, not 404.

5. The web app's OAuth consent page is deployed. Without it the user lands on a page that does not exist, and approves nothing.

Then a client connects to <MCP_SERVER_URL>/mcp, and the user signs in to Mammoth and picks a workspace and a project.

Tests

cd mammoth-mcp-server
python -m pytest tests -q

The tests reach no server. The SDK client and the tools are real; only the HTTP transport under the client is replaced.