magoneai-mcp

MCP connectors for third-party APIs, built on the official MCP Python SDK.

Every connector here talks to somebody else's API. You supply your own credentials and your own storage, and the tool works the same whether it runs inside a platform or on your laptop. If a tool cannot do that, it does not belong in this repository.

MagOneAI

MagOneAI is Magure's AI agent workflow platform: teams define agents with a persona and tools, place them in multi-step workflows, and run them from an app, chat, a schedule or an API, while the platform handles orchestration, retries, credentials and execution tracking. Its agents reach outside services through MCP servers, and this repository is those servers, published so they run anywhere, not only inside MagOneAI.

Where these docs or a tool's description say the platform or the host, they mean whatever runs the connector on a user's behalf: MagOneAI, another MCP host, or you on your laptop. A few tools accept a file reference (a file ID) that a host can swap for the file's bytes before the tool runs. MagOneAI does that; called directly, send the bytes inline as the tool's schema describes.

Names

The project's short name is magoneai. The others each have a reason:

What is here

• magone-mcp-core (src/magone_mcp_core/) - a thin layer over the SDK. It adds the handful of things a connector catalogue needs and the SDK has no opinion about, and gets out of the way otherwise.
• connectors/ - one package per connector: 25 connectors, 269 tools. docs/TOOLS.md lists every tool, generated from the code.
• scripts/ - the gates CI runs on every pull request, each of which you can run locally.

connectors/publication.json records which connectors are ready to publish (18) and which are not yet (7), with the reason for each.

twitter_intel uses an unofficial provider. It calls twitterapi.io, a third-party service, not the official X API. Neither the connector nor the provider is affiliated with or endorsed by X Corp. It is blocked from publication; if you run it yourself, you are responsible for complying with the terms of X and of twitterapi.io.

Documentation

Quickstart

Requires Python 3.11 or later. The published wheel ships only magone-mcp-core; connectors run from a source checkout:

git clone https://github.com/magurelabs/magoneai-mcp
cd magoneai-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e .
MCP_MODE=local python -m connectors.linear

This starts the linear connector, which needs nothing but a Linear API key to make a real call. On start it logs one [error] line, local_bind_clamped_to_loopback. That is expected: local mode is unauthenticated, so the server refuses to listen beyond 127.0.0.1 and says so loudly.

The server speaks MCP over Streamable HTTP at http://127.0.0.1:8000/mcp (PORT changes the port). There is no stdio transport yet, so point your client at the URL. GET /healthz answers {status, name, version, tools}.

From a second terminal in the same virtualenv, list the tools and make one call with the official SDK's client:

import asyncio
import os

from mcp import ClientSession
from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client


async def main() -> None:
    headers = {"X-Linear-Api-Key": os.environ["LINEAR_API_KEY"]}
    async with (
        create_mcp_http_client(headers=headers) as http,
        streamable_http_client("http://127.0.0.1:8000/mcp", http_client=http) as (read, write),
        ClientSession(read, write) as session,
    ):
        await session.initialize()
        tools = await session.list_tools()
        print([tool.name for tool in tools.tools])
        result = await session.call_tool("get_viewer", {})
        print(result.structured_content or result.content)


asyncio.run(main())

LINEAR_API_KEY=lin_api_... python client.py

get_viewer returns the account the key belongs to. Any MCP client works the same way: point it at the URL and send the connector's credential headers.

Replace linear with any directory under connectors/. A connector that needs a third-party library declares it as an extra of the same name, for example pip install -e ".[web_search]"; a connector without one needs only pip install -e .. Several at once: pip install -e ".[database,outlook_email]". Some connectors also need a service of their own: web_search needs a SearXNG instance or a Serper key (see below), and its scrape_url tool needs Crawl4AI (configuration).

Credentials

Each tool declares the request headers it may receive, for example X-Linear-Api-Key, and gets them as a credentials dict. Send them as HTTP headers from your client, or, for a server you run yourself, put them in a JSON file and set MCP_CREDENTIALS_PATH to its path. Keys are the header name without the leading X-, lower-cased, with - replaced by _:

{"linear_api_key": "lin_api_..."}

The file wins: a header cannot override a key the file sets, and can fill only keys the file leaves unset. If the file holds a secret, the host, port, URL, endpoint, connection string and allowlist keys (for example X-Db-Host, X-Allowed-Mailboxes) are never taken from a header, so a caller cannot point your secret at a server of their choosing. With no file, headers supply everything. docs/TOOLS.md shows how many credential headers each tool takes; the tool's credential_headers= in connectors/<name>/server.py names them.

web_search needs no key: it uses a SearXNG instance at SEARXNG_URL (default http://localhost:8888, JSON output enabled), or Serper when SERPER_API_KEY is set. It fetches pages under its own User-Agent and obeys robots.txt when crawling; you are responsible for the terms of the sites it fetches and of the search provider (see configuration).

In a container

One image builds any connector, selected at build time:

docker build --build-arg CONNECTOR=web_search \
  --build-arg SERVER_NAME=io.github.magurelabs/web-search -t magone-mcp-web-search .
docker run --rm -p 8000:8000 -e MCP_MODE=local -e MCP_ALLOW_INSECURE_BIND=1 magone-mcp-web-search

The connector's own extra is installed so it gets what it needs and nothing else. The image runs as uid 10001, never root, and carries LABEL io.modelcontextprotocol.server.name matching the connector's server.json. MCP_ALLOW_INSECURE_BIND=1 is needed because a container must bind beyond loopback; only do that on a network you control, or use platform or hosted mode with authentication instead.

Writing a connector

from mcp.types import ToolAnnotations
from magone_mcp_core import ConnectorServer

server = ConnectorServer(name="example", version="0.1.0")


@server.tool(
    name="search_issues",
    description="Search issues by text.",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False),
)
async def search_issues(query: str, limit: int = 20) -> dict:
    """Return matching issues."""
    return {"issues": [], "query": query}


if __name__ == "__main__":
    server.run(port=8000)

The schema comes from your type hints, which is the right default for a new tool. docs/writing-a-connector.md walks through a complete connector with credentials, tests and every step a pull request needs.

Declaring a tool's permission group

A connection rarely wants a connector's whole surface, so each tool names the group it belongs to and the scopes it needs:

@server.tool(
    name="deleteJiraIssue",
    description="Delete an issue.",
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True),
    permission_group="write_jira",
    required_scopes=["write:jira-work"],
)
async def delete_jira_issue(credentials: dict, issueIdOrKey: str) -> dict: ...

A tool that declares no group falls in default. Both values are carried to a client as _meta on the listed tool, and scripts/permission_group_gate.py fails a tool whose group stayed a comment - a group that is not declared cannot narrow anything, and the failure is silent in the direction that serves every tool to every connection.

A group is a label a host can select on, not a permission the server enforces on its own: see Tool selection is a hint.

Keeping a schema exactly as written

A tool that already exists, and whose schema agents already rely on, should not have that schema regenerated. Derivation invents a title, adds one to every property, and drops every description - a silent behaviour change for any agent reading the description to decide what to pass.

declare_schema keeps the schema byte for byte:

from magone_mcp_core import declare_schema


@server.tool(name="search_web", description="Search the web.", annotations=...)
@declare_schema(
    {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Search query"},
        },
        "required": ["query"],
    }
)
async def search_web(query: str) -> dict: ...

Use it for ported tools. Use type hints for new ones.

What the framework guarantees

Each of these exists because doing it per connector meant it was done differently in each one, or not at all.

Tool selection is a hint, not a guarantee

A caller can narrow one connection to part of a connector: X-MCP-Enabled-Tools names tools outright, X-MCP-Enabled-Groups names permission groups, and names win when both are sent. The server then filters tools/list and refuses a call outside the selection.

Those headers come from the caller, on the very request they narrow. A request that sends neither is served every tool, and nothing stops a client from leaving them out or widening them. Selection therefore restricts nothing on its own. It is only a control when a trusted intermediary you run, such as the host application or a gateway, sets the headers itself and never passes through values chosen by the end client. Do not put a connector in front of a client you do not trust and rely on these headers to limit it.

Groups also only narrow anything where a connector declares more than one. Seven do: atlassian_confluence, atlassian_jira, csv_to_sql, filesystem, linkedin, trino and vanna. In the other 18 every tool is in default, so selecting by group there is all or nothing; select by tool name instead.

The control that does restrict writes, whatever the caller sends, is MCP_READ_ONLY=1 set on the server. Every tool not annotated readOnlyHint=true is dropped from tools/list and refused on tools/call, and a tool with no annotations counts as a write.

Configuration

The variables most deployments touch. docs/configuration.md lists every one, including those individual connectors read.

On prompt injection

Every connector here returns text written by someone outside your trust boundary: an issue description, an email body, a scraped page. That text reaches a model that may also hold write tools.

No authorization model prevents this, because the caller is legitimately authorized for both the read and the write. A server cannot solve prompt injection and this one does not claim to.

Two things it does do. MCP_READ_ONLY=1 makes a deployment that only needs reads incapable of writing, so it cannot be talked into one; that is the control with real blast-radius value. The provenance envelope marks third-party text so a client that wants to treat it as data has something to key on; that is a convention, not a guarantee, and wrapping text does not stop a model reading instructions inside it.

Tests and gates

The whole suite runs with no credentials and no network:

pip install -e ".[dev,all]"
pytest tests/ connectors/ -q

The tests are in three groups: framework tests that need only [dev] (pytest tests/ -m "not requires_connectors"), framework tests that import every connector, and connector tests under connectors/*/tests. Every gate is tested by injecting the defect it exists for.

CI also runs, on every pull request: ruff check and ruff format --check; a golden-schema diff of every tool's input and output schema (scripts/golden_schema_gate.py); a boundary check that refuses platform reach-through (scripts/boundary_gate.py); the tool-contract linter (annotations, property descriptions, logged credentials); dependency, compile, code-health, credential-header, permission-group, publication, manifest and runner-label gates; and the official MCP conformance suite against every connector the change can affect. Each gate is a script under scripts/ that runs locally the same way.

Publication

Each of the 18 publishable connectors carries a server.json (schema 2025-12-11), derived from the connector's own SERVER_NAME and SERVER_VERSION so a manifest cannot describe a server other than the one that runs. scripts/gen_server_json.py --check regenerates and diffs them, and scripts/publication_gate.py fails if a blocked connector ever gains one.

Released artifacts:

• Container images: one per publishable connector on Docker Hub under magureai, named magureai/mcp-<connector>, tagged with the connector's version.
• Python package: the framework as magone-mcp-core on PyPI.
• MCP Registry: one entry per publishable connector under io.github.magurelabs/<connector>.

.github/workflows/publish.yml builds and validates all of this on every pull request that touches it, and publishes only on a manual dispatch inside the protected release environment, after a maintainer approves the run.

History

The connectors originated in Magure's internal platform and are released here by Magure Tech Middle East Ltd. Code comments call that earlier framework v1.

Every carried-over tool's input schema is kept byte for byte with declare_schema and checked on every pull request, because that is the part that would silently change behaviour for an agent already running. Handler bodies were carried across unchanged; scripts/port_status.py counts names a body refers to that do not resolve, and fails if that number rises above zero.

Moving a connector from v1 to this framework is a port: a ported tool kept its v1 schema byte for byte, and pre-port means as it was in v1.

Glossary

Terms the code, comments and docs use without stopping to define them.

Contributing

See CONTRIBUTING.md. Contributions are under the Developer Certificate of Origin rather than a CLA: sign off each commit with git commit -s, and a check on every pull request verifies it. Please read the Code of Conduct. How the project is run is in GOVERNANCE.md; questions go where SUPPORT.md says.

Security

See SECURITY.md. Please report vulnerabilities privately, through GitHub's private vulnerability reporting or to security@magureinc.com, rather than by opening an issue.

Licence

Apache-2.0. See LICENSE and NOTICE.

All product names and trademarks are the property of their respective owners and are used only to identify which API a connector talks to. No connector is affiliated with or endorsed by the owner of the API it wraps, and no vendor logos appear anywhere in this repository.