GoCanvas Server (Read Only)

A minimal Model Context Protocol server that exposes the read-only endpoints of the GoCanvas API v3 as MCP tools. Scope is limited to four areas: Forms, Submissions, Reports, and Reference Data. No create/update/delete operations are exposed.

Tools

Forms

Submissions

Reports

The three PDF tools return the binary PDF inline as base64 (content_base64, content_type, size_bytes) — the server is a pure passthrough and never writes to disk, so the tools work on read-only / ephemeral hosts such as AWS Lambda.

Reference Data

Authentication

refresh_oauth_token forces a fresh bearer token to be fetched and cached. It only applies to server-side OAuth (GOCANVAS_CLIENT_ID / GOCANVAS_CLIENT_SECRET) mode; in passthrough mode the caller owns the token and the server cannot refresh it. It is normally unnecessary — the server fetches a token on startup and refreshes it automatically before expiry and on a 401 — but it is exposed so the agent can rotate the token explicitly. The returned access token is masked.

Setup

This project uses uv. With uv installed, no manual environment setup is required — uv run resolves and installs dependencies (from pyproject.toml) automatically on first launch.

# optional: pre-create the environment
uv sync

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

The server is a thin passthrough to the GoCanvas API and starts with no credentials configured. Authentication is resolved per request, in the following priority order:

Other optional variables:

If no usable credentials are available for a call (no incoming Authorization header and no configured env credentials), the tool returns a clear error — the server itself still starts fine.

Running

Locally over stdio (default)

GOCANVAS_CLIENT_ID=... GOCANVAS_CLIENT_SECRET=... uv run server.py

Publicly over HTTP (e.g. Microsoft 365 Copilot custom agent, AWS Lambda)

Run with an HTTP transport and no GoCanvas credentials — the agent's OAuth bearer token is forwarded per request:

GOCANVAS_TRANSPORT=streamable-http GOCANVAS_HOST=0.0.0.0 GOCANVAS_PORT=8000 uv run server.py

The MCP endpoint is served at /mcp. Point your 365 Copilot custom agent's MCP connection at the public URL and configure its OAuth so it obtains a GoCanvas token; that token is passed through to the GoCanvas API on every tool call. No PDFs or other state are written to disk, so the server runs cleanly on read-only / ephemeral hosts.

Hosting publicly? Set GOCANVAS_ALLOWED_HOSTS to your public domain (or *). The default DNS-rebinding protection allows only localhost and returns HTTP 421 Misdirected Request for any other Host header.

On AWS Lambda

The module exposes an ASGI app (asgi_app()) and a Mangum-wrapped Lambda entry point (lambda_handler), so it runs on Lambda behind an API Gateway HTTP API or a Lambda Function URL with no long-running process. mangum is a declared dependency. Stateless + JSON-response mode is the default (Lambda containers are ephemeral and don't share session state, and API Gateway can't proxy an SSE stream).

A ready-to-deploy AWS SAM template is included (template.yaml); it provisions the function plus a public Function URL:

sam build
sam deploy --guided

The stack outputs the MCP endpoint (<FunctionUrl>/mcp). Point your agent there. Key details baked into the template:

• Handler: server.lambda_handler. Runtime: python3.12 (arm64).
• AuthType: NONE on the Function URL — required so the caller's Authorization bearer reaches the app for passthrough (AWS_IAM would consume it for SigV4). Auth is enforced at the app layer, not by Lambda.
• GOCANVAS_ALLOWED_HOSTS=* so the Function URL's own domain passes the rebinding check. Narrow it to your *.lambda-url.<region>.on.aws (or API Gateway) domain to tighten.
• For server-side OAuth instead of passthrough, set GOCANVAS_CLIENT_ID / GOCANVAS_CLIENT_SECRET in the function's environment (prefer Secrets Manager / SSM references over plaintext).

Payload-size limit. API Gateway / a buffered Function URL caps a response at 6 MB. The PDF tools return the file base64-encoded inline (~33% overhead), so a PDF larger than ~4.5 MB can exceed that limit. Raise MemorySize/Timeout for large forms; for consistently large PDFs, front the function with a Function URL in RESPONSE_STREAM invoke mode or fetch the PDF out-of-band.

MCP client configuration

Use uv run as the command. --directory points uv at this project so it uses the right dependencies regardless of the client's working directory:

{
  "mcpServers": {
    "gocanvas": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/GoCanvas",
        "server.py"
      ],
      "env": {
        "GOCANVAS_CLIENT_ID": "your_client_id",
        "GOCANVAS_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

If uv isn't on the client's PATH, use its absolute path (e.g. ~/.local/bin/uv) as the command.

{
  "mcpServers": {
    "gocanvas": {
      "command": "/absolute/path/to/GoCanvas/.venv/bin/python",
      "args": ["/absolute/path/to/GoCanvas/server.py"],
      "env": {
        "GOCANVAS_CLIENT_ID": "your_client_id",
        "GOCANVAS_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Notes

• Pagination: list tools accept a page argument. Response pagination headers (link, current-page, page-items, total-count, total-pages) are surfaced under a pagination key in the tool result.
• Rate limiting: the server honors 429 Too Many Requests responses, waiting according to the RateLimit-Reset / RateLimit-Remaining headers (or a bounded exponential backoff) before retrying, per GoCanvas best practices.