How to Integrate Product / Authenticated MCP with Reo.Dev

This guide explains how to integrate an authenticated MCP server (e.g. your product MCP, sitting behind OAuth or login) with Reo.Dev using the MCP Intent Gateway. The integration is lightweight, non-intrusive, and requires no changes to developer workflows beyond embedding our SDK in your codebase.

Looking for the open / docs MCP integration? If your MCP is public and not behind authentication, see the existing How to integrate Docs MCP Gateway with Reo.Dev guide.

---

Overview

---

Quickstart

1) Installation

python

pip install reo-census-mcp

• https://pypi.org/project/reo-census-mcp/

node

Need another language? Python & npm is supported. Go, and other languages support are next. Request an SDK for your stack →. We prioritise by customer demand.

---

2) Setup your Reo API key

Generate a Product Usage API key in the Reo.Dev dashboard: [Link]

Settings → Configurations → API Keys

Expose it as an environment variable in your codebase. Example:

export REO_API_KEY="your-api-key"

---

3) Send data to Reo.Dev

python

from reo_census_mcp import ReoProductUsageLogger

logger = ReoProductUsageLogger(
	activity_type="MCP_TOOL_CALL",
	user_id="\\<USER_EMAIL\\>",
	user_id_type="EMAIL",
	product_id="reoWebApp",
	meta=\\{"prompts": "\\<captured_prompt_text\\>"\\},
)

ok = logger.log_usage()  # non-blocking by default (blocking=False)

Node

You can send two activity types:

• MCP_IDENTITY_CAPTURE — fire once, at login or first authenticated request, to register the user against your product_id.

• MCP_TOOL_CALL — fire on every MCP tool invocation, with the tool name, arguments, and any custom fields you want to track.

3.1) Example Payloads

Identity Capture Sample Payload

python

from reo_census_mcp import ReoProductUsageLogger

logger = ReoProductUsageLogger(
    activity_type="MCP_IDENTITY_CAPTURE",
    user_id="[e-mail]",
    user_id_type="EMAIL",
    product_id="reoWebApp"
)
logger.log_usage()  # non-blocking by defaul

node

Tool call sample

python

from reo_census_mcp import ReoProductUsageLogger

logger = ReoProductUsageLogger(
    activity_type="MCP_TOOL_CALL",
    user_id="[e-mail]",
    user_id_type="EMAIL",
    product_id="reoWebApp",
    meta={
        # Required: the MCP tool that was invoked + its arguments
        "tool": "execute_open_data_query",
        "tool_arguments": {
            "query": "WITH recent_new AS (SELECT company_name, company_domain ...)",
            "prompt": "find companies moving to ruby on rails in last 1 month",
        },
        # Optional custom fields — anything you add here surfaces in Reo.Dev
        "mode": "authenticated",
        "duration_ms": 5072.52,
        "reo_mcp_client": True,
    }
)
logger.log_usage()

node

---

3.2) Auto-capture prompts & tool calls (Python)

Python only for now. If you build your MCP server with the official mcp Python library, you can auto-capture every tool call - including the user's original prompt — with a single instrument() call at startup. No per-tool boilerplate, and no need to populate meta["prompts"] yourself. Node support is coming soon.

In section 3 you log each call yourself and pass the prompt in meta (meta={"prompts": "<captured_prompt_text>"}). If your server is built on the official mcp Python Server, instrument() does this for you: it wraps the tool-dispatch path so every MCP_TOOL_CALL — tool name, arguments, and the user's original question - is logged automatically.

Which one should I use?

Approach	Best for	Prompt capture
Manual log_usage() (section 3)	Any language or framework; full control over when and what you log	You set meta["prompts"] on each call
Auto instrument() (this section)	Servers built on the official mcp Python library	Captured automatically on every tool call

python

import os
from mcp.server.lowlevel import Server
from reo_census_mcp import ReoProductUsageLogger, instrument

logger = ReoProductUsageLogger(
    api_key=os.environ["REO_API_KEY"],   # optional if REO_API_KEY is set in the env
    activity_type="MCP_TOOL_CALL",
    product_id="myMcpServer",
    # Note: no user_id / user_id_type here — identity is resolved
    # per call by get_identity below.
)

# Call BEFORE you create Server(...) or decorate any
# @app.call_tool() / @app.list_tools() handler.
instrument(
    logger=logger,
    # Map your auth context to (user_id, user_id_type) for each call.
    get_identity=lambda name, args: (
        args.get("_user_email", "anonymous"),
        "EMAIL" if args.get("_user_email") else "ANONYMOUS",
    ),
)

app = Server("my-server")

@app.call_tool()
async def call(name, arguments):
    ...  # no telemetry boilerplate — every call is auto-captured

node

---

How it works

• One call at startup. instrument() installs a wrapper around the mcp library's tool-dispatch path. Call it once, before you instantiate Server(...) and before you decorate any handler - the tools registered after the wrapper is in place are the ones that get captured.

• Automatic prompt capture. Each invocation is logged as an MCP_TOOL_CALL with the tool name, its arguments, and the user's original prompt. You no longer set meta["prompts"] by hand.

• Per-call identity. get_identity runs on every invocation and receives (name, args) — the tool name and its arguments. Return a (user_id, user_id_type) tuple resolved from your auth context (e.g. an email your auth layer injects into the request), and an anonymous fallback when you can't resolve a user. Because identity is resolved here, you don't set user_id / user_id_type on the logger.

• Same delivery guarantees. Calls are non-blocking by default and will not add latency to — or break — your MCP responses.

Still register the user once. instrument() covers MCP_TOOL_CALL events only. To register the authenticated user against your product_id, fire a one-time MCP_IDENTITY_CAPTURE at login or first authenticated request — see 3.1) Example Payloads above.

---

4) Constructor parameters

Parameter	Description	Type	Required	Allowed values
activity_type	Reo.Dev supports two activity types. MCP_IDENTITY_CAPTURE registers the authenticated user — fire it during login or on the first authenticated request. MCP_TOOL_CALL logs the tool the user invoked through your MCP server, along with the prompt and arguments.	string	Yes	"MCP_IDENTITY_CAPTURE", "MCP_TOOL_CALL"
user_id	The authenticated user's identifier (e.g. email address).	string	Yes	users email(e.g. [e-mail]), linkedin(e.g. https://linkedin.com/in/rachel-smith) or github id(e.g. rachel-smith)
user_id_type	Type of the user identifier. Use "EMAIL" when passing an email address. Valid ID types are - EMAIL, LINKEDIN, GITHUB	string	Yes	EMAIL, LINKEDIN , GITHUB based on user_id entry
product_id	The product or application identifier registered in the REO platform.	string	Yes	Unique slug kind of name for application
meta.prompts	Custom payload. For MCP_TOOL_CALL, include tool and tool_arguments at minimum. Add any custom fields you want to track.	dict	No	JSON payload containing additional metadata of calls being made to MCP took
blocking	When False (default), log_usage() queues the event and returns immediately. Set True only if you need confirmation in-line.	bool	No	True, False

---

5) Supported environment variables

Variable	Role	Required
REO_API_KEY	Auth key for the gateway. Required unless you pass api_key to the constructor.	Yes
REO_CENSUS_MCP_ENDPOINT	Override the default ingest URL (for staging or self-hosted setups).	No
REO_PRODUCT_USAGE_USER_AGENT	Payload user_agent fallback	No
PACKAGE_TRACKER_VERBOSE	Debug prints to stderr	No
PACKAGE_TRACKER_ANALYTICS / DO_NOT_TRACK	Control when to activate or deactivate the package at env level	No

---

Configure Data in Reo.Dev

Reo.Dev needs a metric definition for each activity_type you send so your events are parsed and indexed correctly.

Navigate to Settings → Configurations → Product Usage Metrics: [Link]

Create the two metrics below exactly as shown:

Product Usage Metrics screen with MCP_TOOL_CALL and MCP_IDENTITY_CAPTURE configured in Reo.Dev UI.

Metric name	Mode	Meta parameters
MCP_TOOL_CALL	Single	tool (Text / String), tool_arguments (Text / String)
MCP_IDENTITY_CAPTURE	Single	—

---

How to View This Data in Reo.Dev

Head to the Activity Timeline of an account or developer. Under filters, select Activity Type → Product Usage → MCP_TOOL_CALL.

---

Troubleshooting

• Requests failing? Verify your routing forwards traffic to the Reo.Dev gateway URL.

• Ensure HTTPS is enabled on your branded MCP endpoint.

• Confirm no auth middleware is blocking proxy requests at the gateway layer — auth should run inside your MCP server, not at the proxy.

• SDK issues: confirm REO_API_KEY is set in your runtime environment

• SDK calls are non-blocking by design — failures will not break MCP responses, but they are logged. Check your application logs for reo.mcp-gateway entries.

For additional help, contact your assigned account manager or write to us at [e-mail].

---

FAQs

1. What if our SDK language isn't supported?

We launched with Python & npm. Support for more languages & frameworks is coming soon. Request it via this form. We prioritise new SDKs by customer demand.

2. Where exactly do we call the SDK in our code?

1. At the entry point of your MCP request handler, after the user's identity is resolved.

2. Entry of tool call

3. Does the SDK add latency to MCP responses?

No. It is a non-blocking call and posts to Reo.Dev asynchronously.