How do we adapt an existing API into an MCP connector?

You do not always need to build a custom MCP server from scratch. When a vendor or internal system already exposes a REST API with an OpenAPI or Swagger document, Harriet can generate MCP tools automatically and optionally refine behavior with JavaScript hooks.

This article covers the OpenAPI path, what hooks can adapt without extra code, and when you need a wrapper API or native/sandboxed MCP server instead—especially when user data is keyed by vendor user ID rather than email.

Fastest path: OpenAPI / Swagger connector

1. In Company settings → Integrations, choose New connector.
2. On Connection, select OpenAPI / Swagger.
3. Provide:
   • API base URL (where Harriet sends requests)
   • OpenAPI spec URL (HTTPS) or paste an inline spec if your deployment supports it
4. On Authentication, set the org API key, bearer token, or basic auth as required (IT configures this once; end users never receive the vendor key—Harriet issues per-user authenticated access with subscoped tool permissions). See MCP authorization and stored credentials.
5. Save and Sync tools. Harriet creates one MCP tool per operation (from operationId or method + path).
6. Set tool permissions (groups, confirmation for writes) and attach the connector to skills.

See How to create an MCP connector (Company settings) for the full wizard and How do we connect external tools using MCP? for rollout context. For the credential model (org keys vs per-user Harriet access), see MCP authorization and stored credentials.

Native MCP servers (HTTPS JSON-RPC) and Sandboxed (npx / uvx) packages are alternatives when there is no usable OpenAPI spec—see MCP from GitHub and registries—sandboxed connectors vs skill packages.

What hooks can adapt (no wrapper code)

After sync, enable Request / response hooks on the connector. Handlers receive the signed-in user's context (context.user.email, context.user.employee_id, roles, groups) plus the current tool arguments or response.

Hooks work well for:

• Forcing current-user filters on list tools (inject email or employee ID into query/body parameters)
• Stripping broad search parameters the model might add
• Redacting sensitive fields by role (for example salary or personal phone)
• Filtering arrays in list responses when each row includes owner email or UPN
• Simple reshaping of JSON already in the response

Hooks cannot:

• Call the API a second time (no HTTP, no fetch)
• Load Harriet's user directory or a vendor user map at runtime
• Import npm packages or persist a cache between calls
• Perform email → vendor user ID lookup unless that mapping is already in the current payload

For shared org keys plus hook scoping when rows include owner email, see How can we restrict a shared-key MCP connector to each user's own data?

OpenAPI postprocess shape

For OpenAPI / Swagger connectors, postprocess handlers usually receive a wrapper object, not the raw API body alone:

{
  "status_code": 200,
  "url": "https://api.example.com/v1/devices",
  "method": "GET",
  "result": { }
}

Write postprocess logic against result (and nested arrays inside it). Native and sandboxed MCP tools may return a dict or list directly—use Test hook and the Endpoint AI audit log to confirm the shape for each tool.

Decision checklist

Situation	Recommended approach
REST API + OpenAPI spec + org API key	OpenAPI connector + hooks for scoping/redaction
REST API + OpenAPI + vendor supports per-user OAuth	Per-user OAuth on the connector (preferred over god-mode key)
List endpoint accepts email or returns owner email on rows	OpenAPI + hooks (preprocess filter + postprocess filter)
API only accepts vendor user ID; email lookup is a separate call	Wrapper API or custom MCP tool that performs the join server-side
No OpenAPI; official MCP package exists	Native MCP or Sandboxed npx/uvx
Complex multi-step joins or business rules	Small internal service exposing a narrow OpenAPI spec Harriet calls

Example: email → user ID → devices (Kolide-style)

Endpoint security tools such as Kolide often return devices with an owner ID (or similar opaque identifier), not the owner's email. A typical flow might be:

1. GET /users?email=alice@company.com → { id: "usr_abc123" }
2. GET /users/usr_abc123/devices → device list

Harriet already knows context.user.email before hooks run, but a hook cannot perform step 1 and then rewrite step 2 into one logical call—it only sees one tool invocation at a time and has no network access.

Feasible with hooks alone

• A single list-devices endpoint that accepts email as a query parameter, or
• A list response where each device includes owner email (or UPN you can compare to context.user.email)

In those cases, use the patterns in How can we restrict a shared-key MCP connector to each user's own data?

Not feasible with hooks alone

• Device endpoints that only accept vendor user ID, requiring a prior lookup by email

Practical options:

1. Thin wrapper API (recommended for OpenAPI path)
   Deploy a small internal service with two upstream calls and one Harriet-facing operation, for example GET /me/devices that:

   • Reads the caller identity from a header or signed token Harriet sends, or
   • Trusts Harriet's preprocess hook to pass user_email while the wrapper validates it against your IdP
     The wrapper performs email → Kolide user ID → devices, and returns only that user's devices. Register the wrapper's OpenAPI spec in Harriet—not Kolide's full admin API.

2. Native or sandboxed MCP server
   Publish one or two narrow tools (list_my_devices) that implement the join inside the MCP process. Harriet syncs those tools instead of the raw admin surface.

3. Per-user credentials
   If Kolide (or the vendor) offers OAuth or personal API tokens, configure per-user OAuth so upstream calls run as the employee—see MCP authorization and stored credentials.

4. Do not expose unscoped admin tools
   Even with postprocess filtering, listing all devices with a god-mode key and filtering in JavaScript is fragile for write tools. Disable or deny tools that cannot be scoped in preprocess.

Minimal wrapper sketch (conceptual)

Your wrapper exposes one OpenAPI operation Harriet can sync:

GET /v1/me/devices
Authorization: Bearer <org secret Harriet stores>
X-User-Email: alice@company.com   # injected by preprocess hook, or derived from OAuth

Server-side pseudologic:

1. Resolve email → vendor user ID via Kolide (or your IdP) API.
2. Fetch devices for that ID only.
3. Return JSON { "devices": [ ... ] }.

Harriet connector:

• OpenAPI / Swagger pointing at the wrapper base URL
• Preprocess hook sets X-User-Email from context.user.email (or relies on per-user OAuth at the wrapper)
• Postprocess optional extra redaction

This keeps join logic in your code (testable, auditable) and gives Harriet a small, safe tool surface. Register the wrapper in Harriet with the org API key in Company settings only—employees use Harriet’s per-user, subscoped access, not the top-level vendor key.

Rollout and testing

• Start with read-only list tools; add writes only with confirmation gates in workflows.
• Use Test hook in connector settings and, when enabled, Endpoint AI audit logs to compare arguments and responses.
• Pilot with two Harriet users in different groups before broad skill assignment.
• If Endpoint AI review is enabled, submit the connector through the review queue before production rollout.

Related articles

See How can we restrict a shared-key MCP connector to each user's own data? for hook examples with MDM-style email on device rows, How do we turn MCP tools on or off for specific groups? for per-tool enablement and group restrictions, MCP authorization and stored credentials, How do MCP tools work inside workflow agents?, and What rollout checks should we complete before turning on new integrations or skills?