MCP server

MCP (Model Context Protocol) is the common way AI assistants such as Claude Desktop, Claude Code and Cursor pick up extra tools. The @almyty/mcp-server package plugs one of your almyty gateways (a published set of tools, for example “look up an order” and “issue a refund”) into any of those assistants, so they can use your company’s systems. It is for developers and for people setting up their own AI assistant; most assistants can also connect straight to the gateway’s address, shown on the gateway’s page in the app (see MCP gateways).

You create a gateway in the almyty app, assign tools to it, then point this server at that gateway. The assistant sees your tools as its own.

Prerequisites:

1. Create a gateway in the app (type MCP, UTCP or Skills; the MCP server works with each)
2. Assign tools to the gateway
3. Authenticate: npx @almyty/auth login
4. Run the server with your gateway ID

$ npx @almyty/mcp-server acme/petstore

How it works

The MCP server fetches tools from your almyty gateway and registers them as MCP tools (or skills). When the LLM calls a tool, the server proxies the request through the gateway to the real API. Authentication, rate limiting, and audit logging are handled by the gateway.

It works with assistants on every MCP version in use: the newest, MCP 2026-07-28, and the earlier ones (2024-11-05 to 2025-11-25) that Claude Desktop, Cursor and most editors speak today. The assistant’s first message decides which; there is nothing to set. Towards almyty the server speaks MCP 2026-07-28 too, and switches to the earlier protocol by itself when it reaches an almyty that does not speak 2026-07-28 yet.

Modes

Skill-first mode (default)

Instead of registering every tool as a separate MCP tool (each tool description is sent to the model on every turn, which uses up tokens: the units models read and bill by), skill-first mode registers only two tools:

Skills are registered as MCP prompts, loaded on demand only when the LLM needs them. This dramatically reduces token overhead:

The LLM reads a skill prompt to learn the workflow, then calls almyty_execute with the tool name and parameters from the skill.

Full mode

Registers every tool individually as a standard MCP tool. Use this when your LLM client does not support MCP prompts, or when you have a small number of tools and prefer traditional tool calling:

$ ALMYTY_MODE=full npx @almyty/mcp-server

Each tool keeps what the gateway says about it: its readable name, the full description of its parameters, what it returns (its output schema, so the assistant gets the result as data next to the text) and whether it only reads, changes or deletes something. A tool whose parameter description is not valid JSON Schema is left out, with a line on stderr saying which.

Setup

Prerequisites

Authenticate once before configuring any client:

$ npx @almyty/auth login

almyty is a remote MCP server. Most clients can connect directly via URL, no npm install needed. Use the CLI proxy only if you want skill-first mode (lower token overhead).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "almyty": {
      "url": "https://api.almyty.com/mcp"
    }
  }
}

For a specific gateway:

{
  "mcpServers": {
    "petstore": {
      "url": "https://api.almyty.com/acme/petstore"
    }
  }
}

Restart Claude Desktop. Tools appear under the hammer icon.

Claude Code

$ claude mcp add almyty --transport http https://api.almyty.com/mcp

Or for a specific gateway:

$ claude mcp add petstore --transport http https://api.almyty.com/acme/petstore

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "almyty": { "url": "https://api.almyty.com/mcp" }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "almyty": { "url": "https://api.almyty.com/mcp" }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "almyty": { "url": "https://api.almyty.com/mcp" }
  }
}

OpenAI Codex CLI

~/.codex/config.toml:

[mcp_servers.almyty]
url = "https://api.almyty.com/mcp"

Google Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "almyty": { "url": "https://api.almyty.com/mcp" }
  }
}

Using the CLI proxy instead (optional)

If you want skill-first mode (2 tools instead of N, lower token cost), use the local proxy:

$ npx @almyty/auth login
$ claude mcp add petstore -- npx -y @almyty/mcp-server acme/petstore

Environment variables

Finding your gateway ID

Your gateway ID is org/slug, shown on the gateway detail page. For example, if your org is “acme” and your gateway slug is “petstore”:

$ npx @almyty/mcp-server acme/petstore

Skills as MCP prompts

In skill-first mode, each skill from your gateway is registered as an MCP prompt with the naming pattern skill-<name>. The LLM client can list available prompts and load one when it needs detailed instructions for a specific API workflow.

An overview prompt (almyty-overview) is also registered, providing a compact index of all available tools and skills.

The flow works like this:

1. The LLM sees almyty_execute and almyty_search in its tool list.
2. When the user asks to do something API-related, the LLM calls almyty_search to find relevant tools.
3. The LLM loads the corresponding skill prompt to understand parameters and usage.
4. The LLM calls almyty_execute with the tool name and parameters from the skill.

Skills are only loaded into context when explicitly requested, keeping the baseline token cost low.

Troubleshooting

”No tools found”

The MCP server connected to the backend but no tools were returned. Possible causes:

• No tools assigned to your gateway. Open the almyty dashboard, go to your gateway, and assign tools.
• Wrong gateway ID. Double-check the ALMYTY_GATEWAY_ID value. It should be orgSlug/gatewaySlug, not a UUID.
• No gateways at all. If you have not set ALMYTY_GATEWAY_ID, the server fetches tools from the universal /mcp endpoint. Make sure you have at least one gateway with tools assigned.

Authentication errors

Error: No authentication token found.
Set ALMYTY_TOKEN environment variable or run: npx @almyty/auth login

The MCP server needs a token. If you authenticated interactively with npx @almyty/auth login, the credentials file is read automatically. For MCP config files that run in a different user context (e.g., an IDE subprocess), you may need to set ALMYTY_TOKEN explicitly in the env block.

Connection timeouts

Tool discovery times out after 15 seconds. Tool execution times out after 120 seconds. If your backend is slow or behind a VPN:

• Check that ALMYTY_URL is reachable from the machine running the MCP server.
• If using a self-hosted instance, verify the backend health endpoint: curl https://your-instance/health.

Tools appear in full mode but not skill-first

Skill-first mode requires skills to be configured on the gateway. If your gateway only has raw tools without generated skills, the almyty_search and almyty_execute tools will still work, but there will be no skill prompts to guide the LLM. Either switch to full mode or enable skill generation on your gateway in the dashboard.

stderr messages

The MCP server writes diagnostic output to stderr (stdout is reserved for the MCP JSON-RPC protocol). Messages like almyty: 12 tools, 3 skills (mode: skill-first) on startup are normal and will not interfere with the MCP protocol.