Metadata-Version: 2.4
Name: algenta-mcp
Version: 1.0.8
Summary: Algenta MCP server for Cursor, Codex, and other Model Context Protocol clients.
License-Expression: Apache-2.0
Project-URL: Homepage, https://algenta.ai
Project-URL: Documentation, https://docs.algenta.ai/sdk/mcp
Project-URL: Repository, https://github.com/thyn-ai/algenta
Keywords: mcp,model-context-protocol,cursor,codex,claude,algenta,agent,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: algenta-sdk>=1.0.0
Requires-Dist: mcp==1.28.1
Requires-Dist: fastapi==0.133.1
Requires-Dist: starlette==1.3.1
Requires-Dist: uvicorn==0.51.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: structlog>=24.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: respx; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Algenta MCP Server

<!-- mcp-name: io.github.thyn-ai/algenta -->

Model Context Protocol server for the Algenta API. It gives MCP-compatible agents access to
governed data discovery, exact queries, decisions, simulations, runtime utilities, and account
operations through the same public API contract used by the Algenta SDKs.

Full reference: [docs.algenta.ai/sdk/mcp](https://docs.algenta.ai/sdk/mcp)

## Install

```bash
pipx install algenta-mcp
```

`pip install algenta-mcp` is also supported. The package includes its MCP transport dependencies;
users do not install or manage a separate protocol package.

## Configure

```bash
export ALGENTA_API_KEY="<YOUR_ALGENTA_API_KEY>"
export ALGENTA_BASE_URL="https://api.algenta.ai"
```

Use your deployment URL for self-hosted Algenta. Private deployment profiles fail closed rather
than silently sending traffic to Algenta Cloud.

## Cursor and Claude Desktop

`algenta-mcp` uses stdio by default. Add this server to Cursor's `~/.cursor/mcp.json` or Claude
Desktop's MCP configuration:

```json
{
  "mcpServers": {
    "algenta": {
      "command": "algenta-mcp",
      "env": {
        "ALGENTA_API_KEY": "<YOUR_ALGENTA_API_KEY>",
        "ALGENTA_BASE_URL": "https://api.algenta.ai"
      }
    }
  }
}
```

Restart the client after changing its MCP configuration.

## Codex

Add the stdio server to `~/.codex/config.toml`:

```toml
[mcp_servers.algenta]
command = "algenta-mcp"

[mcp_servers.algenta.env]
ALGENTA_API_KEY = "<YOUR_ALGENTA_API_KEY>"
ALGENTA_BASE_URL = "https://api.algenta.ai"
```

Keep credentials in user-level configuration or environment variables, not in a repository.

## Streamable HTTP

Start the remote transport:

```bash
algenta-mcp --mode http --port 8001
```

The standalone server binds to `127.0.0.1` by default. Set `ALGENTA_MCP_HOST=0.0.0.0` only when
an authenticated container ingress or gateway must expose it to another host.

Connect modern clients to:

```text
http://localhost:8001/mcp
```

The endpoint uses stateless Streamable HTTP and negotiates MCP protocol `2025-11-25`. Algenta pins
the official Python MCP SDK `1.28.1`. Deprecated `/mcp/sse` and `/mcp/messages` routes remain for
older clients but are not the default.

LangChain example:

```python
import os

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "algenta": {
            "transport": "http",
            "url": "http://localhost:8001/mcp",
            "headers": {
                "Authorization": f"Bearer {os.environ['ALGENTA_API_KEY']}"
            },
        }
    }
)

tools = await client.get_tools()
```

## Verify

The human-readable discovery route is available alongside the protocol endpoint:

```bash
curl -s http://localhost:8001/mcp/tools | jq '.tools | length'
```

In an MCP client, call `get_contract` first, then use `list_data` and `get_data_summary` before
querying a dataset. Tool names, descriptions, and input schemas are returned by MCP `tools/list`.

## Security

- Tool calls use `Authorization: Bearer <ALGENTA_API_KEY>` or the configured process credential.
- Streamable HTTP validates `Host` and `Origin` to prevent DNS-rebinding access.
- Standalone HTTP binds to loopback unless `ALGENTA_MCP_HOST` is explicitly changed.
- Error payloads redact API-key material.
- `ALGENTA_BASE_URL` is required when cloud access is disabled.
- Put an authenticating gateway in front of a publicly reachable standalone MCP port.

## Compatibility

Canonical environment variables are `ALGENTA_API_KEY` and `ALGENTA_BASE_URL`. Legacy
`DE_API_KEY`, `DE_BASE_URL`, and `ALGENTA_API_URL` remain accepted for existing deployments.

## License

Apache-2.0
