Metadata-Version: 2.4
Name: mantivor-collector
Version: 0.1.1
Summary: Mantivor — runtime monitoring collector for MCP servers
Project-URL: Homepage, https://mantivor.io
Project-URL: Documentation, https://mantivor.io/docs
Project-URL: Issues, https://mantivor.io/support
License: Mantivor Collector — Proprietary Licence
        
        Copyright (c) 2026 Fahad Ali, trading as Mantivor. All rights reserved.
        
        
        THIS IS A WORKING DRAFT, NOT LEGAL ADVICE.
        
        It is pending review by a qualified solicitor and may change. It states the
        licensor's current intent in good faith. If anything here conflicts with a
        signed agreement you have with the licensor, that agreement governs.
        
        
        1. DEFINITIONS
        
           "Licensor" means Fahad Ali, an individual trading as Mantivor. No company is
           registered at the date of this licence. Where this licence is later assigned
           to a company formed by the Licensor, that company becomes the Licensor and
           this licence continues unchanged in all other respects.
        
           "Software" means the Mantivor runtime monitoring collector distributed under
           the package name `mantivor-collector`, including its source code, object code
           and accompanying files.
        
           "Mantivor Service" means the hosted Mantivor service operated by the Licensor.
        
           "Your Organisation" means an organisation account on the Mantivor Service that
           you own, or are authorised by its owner to act for.
        
           "You" means the individual or entity exercising the permission granted in
           section 2.
        
        
        2. GRANT OF PERMISSION
        
           The Licensor grants you a personal, non-exclusive, non-transferable,
           revocable permission to install and run the Software for the sole purpose of
           interacting with Your Organisation on the Mantivor Service.
        
           That is the entire grant. Installing the Software on machines you control —
           including developer workstations, agent hosts and continuous-integration
           runners — and running it against Your Organisation is permitted. Any other
           use is not.
        
        
        3. RESTRICTIONS
        
           Except to the extent that applicable law expressly overrides a restriction
           below, and only to that extent, you may not:
        
           (a) redistribute, publish, sell, rent, lease, sublicense, or otherwise make
               the Software available to any third party;
        
           (b) modify, adapt, translate, or create derivative works of the Software;
        
           (c) reverse engineer, decompile, or disassemble the Software, or otherwise
               attempt to derive its source code, algorithms, or underlying ideas;
        
           (d) remove, obscure, or alter any copyright, trademark, or other proprietary
               notice in or on the Software;
        
           (e) use the Software to interact with any Mantivor organisation that is not
               Your Organisation;
        
           (f) use the Software to build, train, or improve a competing product or
               service.
        
        
        4. RESERVATION OF RIGHTS
        
           The Software is licensed, not sold. The Licensor retains all right, title and
           interest in and to the Software, including all intellectual property rights.
           No rights are granted except those expressly stated in section 2. No right is
           granted by implication, estoppel, or otherwise.
        
        
        5. THIRD-PARTY COMPONENTS
        
           The Software depends on separately licensed open-source components, which
           remain governed by their own licences. Nothing in this licence limits your
           rights under those licences with respect to those components.
        
        
        6. TERMINATION
        
           This permission terminates automatically if you breach any term of this
           licence, and may be revoked by the Licensor at any time. On termination you
           must stop using the Software and remove all copies in your possession or
           control. Sections 3, 4, 7 and 8 survive termination.
        
        
        7. NO WARRANTY
        
           THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
           IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
           FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
        
           The Software reports the results of automated security analysis. It does not
           guarantee that any system is secure, that any attack will be detected, or
           that any detection is correct, and its output is not a substitute for your
           own security judgement.
        
           The Software forwards traffic between your agent and an MCP server. It is not
           a security control and does not block, filter or alter that traffic.
        
        
        8. LIMITATION OF LIABILITY
        
           TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
           LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN
           ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
           CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
           Nothing in this licence excludes or limits liability for death or personal
           injury caused by negligence, for fraud or fraudulent misrepresentation, or
           for any other liability that cannot lawfully be excluded or limited.
        
        
        9. GOVERNING LAW
        
           This licence is governed by the laws of England and Wales, and the courts of
           England and Wales have exclusive jurisdiction over any dispute arising from
           it.
        
        
        Questions about this licence: contact@mantivor.io
License-File: LICENSE
Keywords: mcp,model-context-protocol,monitoring,proxy,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: anyio>=4.5
Requires-Dist: httpx>=0.27.0
Requires-Dist: mantivor>=0.1.2
Requires-Dist: mcp<2,>=1.29.0
Requires-Dist: typer-slim<0.22,>=0.12.0
Description-Content-Type: text/markdown

# mantivor-collector

Runtime security monitoring for an MCP server you run.

The collector is a **stdio proxy**. You put it between your agent and one MCP
server: your agent launches the collector instead of the server, and the
collector launches the server. Every response the server returns is forwarded to
your agent **byte for byte**, and inspected on the way past for things that look
like an attack on the agent — hidden instructions, role injection, encoded
payloads and exfiltration patterns in tool output. What it finds is reported to
your [Mantivor](https://mantivor.io) organisation, where you read it in the
dashboard. The rules it matches against are downloaded at startup and change
over time, so what it detects is not fixed by the version you install.

It is a monitor, not a firewall. It never blocks, filters or alters a response.

## Before it will do anything

Two things have to be true, and it is better to read them here than to meet them
as an error on your first run:

1. **You need a Mantivor organisation and an API key.** Sign up at
   [mantivor.io](https://mantivor.io), add the server you want to monitor, then
   create a key under **Settings → API keys**. A collector key needs exactly two
   scopes, **`runtime:write`** and **`ruleset:read`**. Scopes are fixed when a
   key is created — to change them, mint a new key.
2. **A person must confirm, in the dashboard, that they are authorised to
   observe that server.** An API key cannot grant this to itself. The
   confirmation lasts **30 days** and can be withdrawn at any time.

Without the first, the collector exits and tells you to log in. Without the
second, it starts, forwards your traffic normally, and tells you loudly that it
is not monitoring.

```bash
pip install mantivor-collector
mantivor login                       # the `mantivor` CLI installs alongside this package
mantivor-collector run \
  --server-id srv_a1b2c3 \
  --upstream python --upstream-arg -m acme.mcp
```

`mantivor-collector doctor --server-id srv_a1b2c3` checks every one of those
gates before you wire anything into your agent. Start there.

## Names that look like typos but are not

This package is `mantivor-collector`, but it imports as `vorlox_collector` and
reads environment variables called `VORLOX_API_KEY` and `VORLOX_API_URL`.

Vorlox was this product's former name. The import package and the environment
variables deliberately kept the old spelling: renaming them would break every
existing install and pipeline for no functional gain. They are the correct,
current names — not stale documentation, and not something you need to work
around.

## What it does to your traffic

**Nothing.** The response your agent receives is always the one your server
sent, byte for byte. Inspection happens alongside; if it fails, the call
completes normally.

**If the collector cannot monitor, it keeps forwarding.** A revoked key, an
expired authorisation, a plan change, an unreachable API — all of them stop
*detection*. None of them stops your traffic, and none of them exits. You get a
loud, repeated warning on stderr instead of a broken agent.

That is one rule to remember: **if something is wrong, your traffic still flows
and Mantivor tells you it is not watching.**

Consent is re-checked every five minutes while running. If it is withdrawn or
expires mid-session, observation stops there and then, buffered events are
discarded, and forwarding continues.

## What leaves your machine

By default, **response text does not**. A reported event carries which rule
matched, its category and weight, where in the response it matched, and a score.
It does not carry the matched text.

You can opt in with `--redaction none`, which adds up to 200 characters of the
matched text per signal. The setting is recorded on every event, so the
dashboard shows which choice produced each record.

Both the startup banner and `mantivor-collector doctor` state the current
setting in the same words.

## Diagnosing it

```
mantivor-collector doctor --server-id srv_a1b2c3
```

Runs every check the collector runs at startup and prints each verdict —
credential, connectivity, scopes, ruleset, redaction, server, consent,
entitlement — exiting non-zero on the first failure. Paste this output into a
support request; it is what we would ask for.

## Credentials

The collector reads the key stored by `mantivor login` (from the `mantivor` CLI,
which is installed as a dependency of this package), or `VORLOX_API_KEY` if set,
which wins. A collector key cannot read your findings, start scans, or register
servers.

**Use one key per collector host.** Revoking then affects that machine alone.
Each install also generates a random collector id, so the same key presenting
from two machines is visible in your organisation's records — which is how a
cloned or imaged machine gets noticed.

## Detection rules

The collector downloads its detection rules from the Mantivor API at startup and
holds them in memory. They are never written to disk.

Being direct about what that does and does not achieve:

> A customer with a valid key can extract the ruleset from the collector's
> memory, and we are not preventing that — no design that runs on someone
> else's machine can. What changes is that bulk anonymous access ends and access
> becomes attributable.

Concretely: the rules are not in a package anyone can download without an
account, every full fetch is tied to a key and recorded, and access is
revocable. We do not claim more than that.

We also do not vary the rules per customer to trace leaks. Doing so would mean
different customers get different detection, trading your protection for our
attribution, and that is not a trade we will make.

If the rules cannot be downloaded, or require a newer collector than you have
installed, the collector **refuses them entirely** and detects nothing rather
than applying the part it understands — a partially applied ruleset scores
lower, so a real attack would be reported as clean. It tells you loudly, and
keeps forwarding your traffic.

## Buffering and delivery

Events are buffered in memory, never on disk, and posted to your Mantivor
organisation in batches of up to 100. A batch is sent **every 30 seconds, and
immediately once a batch's worth has accumulated** — so a burst does not sit
waiting for a tick, and a quiet server's single detection does not sit for
half an hour. A last batch is sent when your agent disconnects.

The buffer holds at most 1000 events and drops anything older than 6 hours; when
it fills, the oldest are dropped and the count is reported. **Buffered events are
lost if the process is killed** — that is the cost of never writing your
response data to disk, and the flush interval is what keeps the window small.

On a refusal:

| | |
|---|---|
| Daily event limit reached (`429`) | Buffered events are **dropped**, not held — holding them would deliver a flood when the window reopens. The count is reported. |
| Our server erred, or the network failed | The batch goes back on the queue, oldest first, and is retried. |
| Authorisation withdrawn or expired | The buffer is **discarded** and monitoring stops. Your traffic keeps flowing. |
| The batch was malformed | Discarded rather than retried forever, and reported as our bug. |

A retried batch cannot double-report: each event is stamped with a unique id
when it is detected, not when it is sent, so a re-send carries the same ids and
the API recognises them.

`mantivor-collector` prints a status line after each delivery —
`observed=… events=… delivered=… buffered=… dropped=…` — so "detected" and
"actually reached Mantivor" are two numbers you can compare rather than one you
have to trust.

## Install size

This package depends on the MCP SDK, which brings roughly 44 MB of
dependencies — including a web server framework it uses for transports a stdio
proxy never touches. That is why the collector is a separate package from the
`mantivor` CLI, which stays at about 2.7 MB for CI use.

## Licence

Proprietary. Installing and running it against your own Mantivor organisation is
permitted; redistribution and modification are not. The full terms ship in the
package as `LICENSE`.

Support: [mantivor.io/support](https://mantivor.io/support) ·
Questions about the licence: contact@mantivor.io
