simpleinout-mcp

Simple In/Out MCP Service — a stateless HTTP MCP server wrapping the Simple In/Out APIv4, covering company info, in/out statuses, users, groups, beacons, geofences, networks, announcements, and roles.

Tech stack: Python 3.12 + uv + FastMCP (Starlette/Uvicorn)

It follows the MSPbots Vendor MCP Service SOP: stateless, no stored credentials, per-request header authentication only (no environment-variable credential fallback on the HTTP path).

Scope

15 tools, going beyond MSPbots' historical usage (which was just 1 endpoint — "Companies") to cover the broader resource catalog, prioritizing the core check-in/check-out status feature plus the read-side of every other resource category the API exposes.

Related MCP server: concept2-mcp-server

Authentication

Simple In/Out's API is pure OAuth2 with no non-redirect alternative (confirmed against the official docs — only authorization_code and refresh_token grants exist; no client_credentials, no API key). However, the redirect step is only needed once, by a human, out-of-band — not by this service at runtime:

1. One-time setup (a person does this, not the MCP): visit GET /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&scope=write, log in, approve. Exchange the returned code for an access_token + refresh_token via POST /oauth/token with grant_type=authorization_code.

2. Ongoing operation (this service does this, per call): exchange the refresh_token for a fresh access_token via POST /oauth/token with grant_type=refresh_token — this grant needs only client_id + client_secret + refresh_token, no redirect_uri. Since access tokens are cheap to re-mint and this service must stay stateless, it does this on every call rather than caching (no cross-request caching of tokens either — see SOP §3.4).

So the only credentials this service needs are client_id, client_secret, and a refresh_token obtained once via step 1. These values are supplied per-request via HTTP headers only — there is no environment variable or config field for them, and no fallback that would read them from the environment.

Quick Start

Docker (recommended)

docker compose up --build

The server starts on http://localhost:8080.

Local (uv)

uv sync
python -m simpleinout_mcp

Health Check

curl http://localhost:8080/health
# {"status": "ok"}

No credentials are required for the health endpoint (it is a pure local liveness probe and does not call the Simple In/Out API).

HEADER 授权参数说明 (Authentication)

Every request to /mcp must include all three of the following HTTP headers:

Missing any of the three headers returns 401 Unauthorized with the list of required header names in the response body.

Environment Variables

Non-credential configuration only — see Authentication above for how credentials are supplied.

MCP Endpoint

POST http://localhost:8080/mcp

Connect your MCP client with:

• Transport: http (Streamable HTTP)

• Headers: X-SimpleInOut-Client-Id, X-SimpleInOut-Client-Secret, X-SimpleInOut-Refresh-Token (all required)

Available Tools (15)

All tools are read-only except simpleinout_create_my_status and simpleinout_create_user_status. page_size on the list_groups/list_beacons/list_fences/list_networks/list_announcements tools is clamped server-side to 200 (Simple In/Out's docs specify a default of 25 but do not document a hard maximum, so the SOP's fallback ceiling is used).

测试示例 (Test Example)

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-SimpleInOut-Client-Id: <client_id>" \
  -H "X-SimpleInOut-Client-Secret: <client_secret>" \
  -H "X-SimpleInOut-Refresh-Token: <refresh_token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "simpleinout_get_current_user", "arguments": {} }
  }'

Per SOP §12, run initialize → tools/list → tools/call in that order with your own test credentials before considering the service verified end-to-end — /health returning 200 does not imply /mcp is usable.

Known Gaps

• ⚠️ Not yet tested against a live Simple In/Out account. All 15 tools checked structurally only (MCP handshake, tools-list, schema validity, /health, gateway 401 credential-gating). Per the parent ClickUp task, the previously-applied API client has expired; a new one has been requested via email (registering MSPbots' own MCP Management Service OAuth callback URLs as the redirect URIs) and is pending Simple In/Out's reply. Once a client_id/secret comes back, someone still needs to do the one-time interactive authorization to obtain the initial refresh_token before this can be tested end-to-end.

• Endpoint paths/params verified directly against the docs' verbatim Endpoint/Route/Parameters blocks (page text extraction, not an AI-summarized fetch) — not guessed.

• "Settings" has no documented endpoint at all — it only appears as a timestamp key inside the meta.last_updated_at object on every response, not as its own resource. Not built as a tool.

• "Favorites" is not a top-level resource — all favorites actions live under /users/my/favorites (bulk-replace via POST) and /users/my/statuses/favorite//hide//unfavorite (per-item). No GET /favorites exists. Not built as a tool in this 15-tool scope; the POST /users/my/favorites bulk-replace endpoint could be added if favorites management is needed.

• Statuses have no update/PATCH — a status is an immutable log entry; "changing" status means creating a new one (simpleinout_create_my_status/simpleinout_create_user_status).

• Scope is limited to the 15 operations above, not the full API surface (which also includes user/role/group create-update-delete, beacon/fence/network create-update-delete, and the newer Reporting API endpoint mentioned in Simple In/Out's changelog).

• simpleinout_list_users has no documented pagination parameters in the vendor docs (unlike groups/beacons/fences/networks/announcements), so no page/page_size args were added to it.

API Reference

• Simple In/Out API v4 Documentation

• How to request API credentials (email help@simplymadeapps.com, subject "API")