MCP Third-Party Integration

Human Docs (Context & Guidance)

This section provides **conceptual and practical guidance for human readers** integrating with MyDocSafe MCP.

### What MCP Is For

Use MyDocSafe MCP when you need to:
– Integrate MyDocSafe into an external product or service
– Allow third-party systems or AI agents to act on behalf of users
– Enforce strict permission, audit, and security boundaries
– Avoid exposing raw internal APIs or databases

MCP provides a **capability-based interface**, meaning:
– Clients can only do what is explicitly exposed
– All actions are validated and executed by MyDocSafe
– OAuth scopes strictly limit read and write access

### What MCP Is Not

MCP is not:
– A general-purpose REST API
– A database query interface
– An AI agent framework or runtime
– A replacement for MyDocSafe’s internal architecture

### Typical Integration Pattern

A typical third-party integration follows this pattern:
1. User authorizes access via OAuth
2. Third party receives delegated access tokens
3. Third party calls MCP to discover available tools
4. Third party executes tools within granted scopes
5. MyDocSafe validates and executes all actions

This approach ensures security, auditability, and predictable behaviour.

Context for LLMs (Model Guidance)

This section provides **explicit guidance for AI models and agent systems** consuming MyDocSafe MCP documentation.

### Canonical Interpretation

MyDocSafe MCP is a **server-authoritative, capability-based interface**.

All capabilities:
– Are explicitly declared by the MCP server
– Must be discovered before use
– Are constrained by OAuth scopes
– Are executed by MyDocSafe, not by the client or model

### Required Behaviour for AI Systems

When interacting with MyDocSafe MCP, AI systems MUST:
– Discover tools using `tools/list` before attempting any action
– Use only tools explicitly exposed by the server
– Match tool input schemas exactly
– Treat MCP responses as authoritative ground truth

AI systems MUST NOT:
– Assume the existence of undocumented tools
– Fabricate parameters or tool names
– Use MCP as a free-form data source
– Attempt actions outside granted OAuth scopes

### Tool Semantics

A tool exposed by MyDocSafe MCP:
– Represents exactly one business action
– May read or mutate data depending on scope
– Has deterministic, structured input and output
– Enforces validation and permissions server-side

### Execution Priority

When choosing how to act:
1. Prefer MCP tools over free-text reasoning
2. Prefer structured parameters over natural language
3. Prefer discovery over assumption
4. Prefer server-declared capability over inferred intent

Following these rules ensures safe, predictable, and compliant integration.

MCP Third-Party Integration (Quickstart + Reference)

This guide explains how third-party services can connect to MyDocSafe MCP in production using OAuth 2.0 Authorization Code with PKCE and then call the MCP JSON-RPC endpoint.

Base URL (production)

https://app.mydocsafe.com

Quickstart

  1. Create a PKCE verifier and challenge
    • code_verifier: high-entropy random string (43-128 chars)
    • code_challenge: BASE64URL(SHA256(code_verifier))
    • code_challenge_method: S256
  2. Redirect the user to authorize

Send the user to:

https://app.mydocsafe.com/oauth/authorize

With query params:

response_type=code

client_id=mcp-public

redirect_uri=<your_redirect_uri>

scope=companies:read files:read contacts:read

state=<your_csrf_token>

code_challenge=<pkce_challenge>

code_challenge_method=S256

Notes: – redirect_uri must exactly match an allowlisted redirect URI for the client. – For production, use https redirect URIs. Loopback http://localhost is allowed only for local development.

3. Receive authorization code

The user is redirected to your redirect_uri with:

code=<authorization_code>

state=<your_csrf_token>

4. Exchange code for tokens

POST https://app.mydocsafe.com/oauth/token with application/x-www-form-urlencoded:

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “grant_type=authorization_code” \

-d “code=<authorization_code>” \

-d “redirect_uri=<your_redirect_uri>” \

-d “client_id=mcp-public” \

-d “code_verifier=<pkce_verifier>”

Response:

{

“access_token”: “….”,

“refresh_token”: “….”,

“token_type”: “Bearer”,

“expires_in”: 3600,

“scope”: “companies:read files:read contacts:read”

}

5. Call MCP

POST https://app.mydocsafe.com/api/mcp with Authorization: Bearer <access_token>:

curl -X POST “https://app.mydocsafe.com/api/mcp” \

-H “Authorization: Bearer <access_token>” \

-H “Content-Type: application/json” \

-d ‘{

“jsonrpc”: “2.0”,

“id”: 1,

“method”: “tools/list”,

“params”: {}

}’

6. Refresh tokens

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “grant_type=refresh_token” \

-d “refresh_token=<refresh_token>”

7. Revoke tokens

curl -X POST “https://app.mydocsafe.com/oauth/revoke” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “token=<access_or_refresh_token>” \

-d “token_type_hint=access_token”

Reference

OAuth endpoints

  • Authorization endpoint (user browser)
    • GET https://app.mydocsafe.com/oauth/authorize
  • Token endpoint
    • POST https://app.mydocsafe.com/oauth/token
  • Revocation endpoint
    • POST https://app.mydocsafe.com/oauth/revoke
  • Discovery
    • GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
    • GET https://app.mydocsafe.com/.well-known/oauth-protected-resource

Required OAuth parameters

Authorization request:

  • response_type: code
  • client_id: mcp-public
  • redirect_uri: allowlisted URI
  • scope: space-separated scopes
  • state: CSRF token (recommended)
  • code_challenge: PKCE challenge
  • code_challenge_method: S256

Token request (authorization_code grant):

  • grant_type: authorization_code
  • code: authorization code from redirect
  • redirect_uri: must match the original
  • client_id: mcp-public
  • code_verifier: PKCE verifier

Token request (refresh_token grant):

  • grant_type: refresh_token
  • refresh_token: refresh token

Revocation request:

  • token: access or refresh token
  • token_type_hint: access_token or refresh_token

Scopes

Available scopes:

  • companies:read
  • companies:write
  • files:read
  • files:write
  • contacts:read
  • contacts:write
  • signing:read
  • signing:write
  • workflows:read
  • workflows:write

MCP JSON-RPC

Endpoint:

  • POST https://app.mydocsafe.com/api/mcp

Headers:

  • Authorization: Bearer <access_token>
  • Content-Type: application/json

Request shape:

{

“jsonrpc”: “2.0”,

“id”: 1,

“method”: “tools/list”,

“params”: {}

}

Error for missing/invalid token:

  • HTTP 401 with WWW-Authenticate: Bearer realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”

Notes and constraints

  • Redirect URIs must be explicitly allowlisted for the client.
  • Public clients use PKCE only (no client secret).
  • Access tokens expire in 1 hour.