sharepoint-mcp

Node.js MCP server for Microsoft SharePoint via Microsoft Graph, built from the FortisAI-compatible MCP skeleton. It includes:

• SharePoint site, search, drive, folder, metadata, text-content, and file-management tools

• Vault-backed Microsoft Graph token lookup by user id

• Postgres-backed configuration management

• stdio and HTTP MCP transports

• Security and operational defaults for production-style patterns

Purpose

This repository is a local starting point for a FortisAI SharePoint MCP that can later sit behind an OpenAPI gateway. It supports both read-oriented SharePoint discovery/retrieval and admin-gated file-management operations. Mutating tools remain protected by MCP_ADMIN_AUTH_KEY when configured.

Related MCP server: SharePoint MCP Server

SharePoint Architecture

Runtime flow:

1. src/index.js boots the app, creates services, and connects MCP stdio transport.

2. src/config/env.js loads and validates environment configuration.

3. src/services/configStore.js handles Postgres persistence.

4. src/services/vault.js handles Vault operations and write retry queue.

5. src/services/security.js redacts sensitive fields.

6. src/mcp/server.js registers MCP tools and applies auth/error wrappers.

7. src/http/server.js exposes MCP over HTTP with auth, limits, and access logs.

8. src/http/index.js boots the dedicated HTTP MCP process.

9. src/start-both.js starts stdio and HTTP as separate child processes.

Local infrastructure:

• docker-compose.yml runs Postgres and Vault for local development.

• docker-compose.external.yml runs only the MCP app against external Postgres and Vault services.

• initdb/001_config.sh creates and seeds the app-prefixed config table.

Registering The MCP Server

This repository can be registered with MCP clients in either stdio mode or HTTP mode.

For local development, stdio is the simplest option:

{
	"mcpServers": {
		"sharepoint-mcp": {
			"command": "npm",
			"args": ["run", "start:stdio"],
			"cwd": "/Users/lesterjohn/Documents/Github/sharepoint-mcp"
		}
	}
}

For HTTP-capable clients, use npm run start:http and point the client at the /mcp endpoint.

Codex

Use stdio for Codex unless you specifically need HTTP. Add the server to your Codex MCP configuration using the local workspace path:

• Config file: ~/.codex/config.toml

• Transport: stdio

{
	"mcpServers": {
		"sharepoint-mcp": {
			"command": "npm",
			"args": ["run", "start:stdio"],
			"cwd": "/Users/lesterjohn/Documents/Github/sharepoint-mcp"
		}
	}
}

If you prefer HTTP, run npm run start:http in this repository and configure Codex to send MCP requests to http://127.0.0.1:3000/mcp.

VS Code

Use stdio in VS Code for local workspace access, or HTTP if your setup routes MCP servers over a local endpoint:

• Config file: .vscode/mcp.json

• Transport: stdio or HTTP

{
	"command": "npm",
	"args": ["run", "start:stdio"],
	"cwd": "/Users/lesterjohn/Documents/Github/sharepoint-mcp"
}

If your VS Code setup uses HTTP transport, point it at http://127.0.0.1:3000/mcp after starting npm run start:http.

Claude

For Claude Desktop, use stdio and add an MCP server entry that launches the process from this repository:

• Config file: ~/Library/Application Support/Claude/claude_desktop_config.json

• Transport: stdio

{
	"mcpServers": {
		"sharepoint-mcp": {
			"command": "npm",
			"args": ["run", "start:stdio"],
			"cwd": "/Users/lesterjohn/Documents/Github/sharepoint-mcp"
		}
	}
}

If you are using a Claude setup that supports MCP over HTTP, point it at http://127.0.0.1:3000/mcp.

Tool Catalog

Shared Contract (All Tools)

• Transport: MCP tools are registered in src/mcp/server.js and return MCP text content containing JSON.

• Response shape:

  • Success: { ok: true, status: 200, data: <payload> }

  • Handled not found paths: { ok: false, status: 404, error: <message> }

  • Errors: { ok: false, status: 401|500, error: <message> } with MCP isError: true

• Redaction: output is redacted unless MCP_ALLOW_SENSITIVE_OUTPUT=true.

• Authorization: when MCP_ADMIN_AUTH_KEY is set, admin/mutating tools require authorizationKey that exactly matches it.

• User scope fallback: when userId is omitted for config/token-indexed operations, default user scope is used (MCP_CONFIG_DEFAULT_USER_ID, default default).

Tool Definitions

query_suggestion_schema_discovery

• Classification: read-only, low-risk.

• Use when: you need a complete schema and usage playbook for every tool exposed by this MCP server.

• Do not use when: you already know the exact tool to call and only need a direct invocation.

• Parameters:

  • objective?: optional natural-language goal used to prioritize a recommended tool sequence.

  • tools?: optional list of tool names to scope discovery.

  • includeSchemas?: optional boolean, defaults to true.

  • includeExamples?: optional boolean, defaults to true.

• Response data includes:

  • summary.totalTools and category counts.

  • objectiveRecommendations: best-next tools for the provided objective.

  • tools[]: per-tool description, risk category, when-to-use guidance, follow-up tools, and input schema summary.

• Example: { "objective": "discover SharePoint files", "includeSchemas": true }

sharepoint_connection_info

• Classification: read-only, low-risk.

• Use when: validating Graph/Vault token-source wiring.

• Do not use when: you need live SharePoint content.

• Prerequisites: SharePoint env parsed at startup.

• Parameters: none.

• Environment behavior: reports configured token-source strategy and limits; never returns access token values.

• Common failures: service startup/config errors.

• Recommended tools: run before sharepoint_list_sites during troubleshooting.

• Example: {}

sharepoint_list_sites

• Classification: read-only, low-risk.

• Use when: discovering sites by text query.

• Do not use when: you already have exact siteId (use sharepoint_get_site).

• Prerequisites: valid Graph access token via direct arg, env, or Vault.

• Parameters:

  • search?: non-empty string.

  • limit?: integer 1..100.

  • userId?: non-empty string.

  • accessToken?: non-empty string (direct override).

• Environment behavior: token resolution order is accessToken -> SHAREPOINT_ACCESS_TOKEN -> Vault path template.

• Common failures: missing/expired token, Graph 401/403, invalid limit.

• Follow-up tools: sharepoint_list_drives, sharepoint_search.

• Example: { "search": "finance", "limit": 10, "userId": "default" }

sharepoint_get_site

• Classification: read-only, low-risk.

• Use when: resolving site metadata by known Graph siteId.

• Do not use when: site discovery is needed (use sharepoint_list_sites).

• Prerequisites: valid Graph token.

• Parameters: siteId (required, non-empty), optional userId, optional accessToken.

• Common failures: invalid siteId, unauthorized token, site not found.

• Follow-up tools: sharepoint_list_drives.

• Example: { "siteId": "contoso.sharepoint.com,abc,def" }

sharepoint_search

• Classification: read-only, low-risk.

• Use when: searching entities (site, drive, driveItem, list, listItem) from one query.

• Do not use when: listing a known folder path (use sharepoint_list_folder).

• Prerequisites: valid Graph token and tenant search permissions.

• Parameters:

  • query: required non-empty string.

  • entityTypes?: array of enum values above.

  • limit?: integer 1..100.

  • userId?, accessToken?.

• Common failures: query validation, Graph permission scopes, throttling.

• Follow-up tools: sharepoint_get_file_metadata, sharepoint_get_file_text.

• Example: { "query": "Q4 roadmap", "entityTypes": ["driveItem"], "limit": 25 }

sharepoint_list_drives

• Classification: read-only, low-risk.

• Use when: listing document libraries for a known site.

• Do not use when: site ID is unknown.

• Prerequisites: valid siteId and Graph token.

• Parameters: siteId (required), limit? (1..100), userId?, accessToken?.

• Common failures: invalid site identifier, unauthorized token.

• Follow-up tools: sharepoint_list_folder.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "limit": 20 }

sharepoint_list_folder

• Classification: read-only, low-risk.

• Use when: enumerating children in a document library folder.

• Do not use when: downloading file body text (use sharepoint_get_file_text).

• Prerequisites: valid Graph token and addressable location.

• Parameters:

  • siteId?, driveId?, itemId?, path? (location selectors).

  • limit?: integer 1..100.

  • userId?, accessToken?.

• Parameter constraints: pass a resolvable location set; typically siteId with one of itemId or path.

• Common failures: ambiguous or invalid location parameters, permission denials.

• Follow-up tools: sharepoint_get_file_metadata, sharepoint_get_file_text.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "path": "Shared Documents/Plans", "limit": 50 }

sharepoint_get_file_metadata

• Classification: read-only, low-risk.

• Use when: reading file metadata without body content.

• Do not use when: you need actual file text.

• Prerequisites: valid Graph token and file locator.

• Parameters: optional siteId, driveId, itemId, path, plus optional userId/accessToken.

• Common failures: unresolved item selector, permission denied.

• Follow-up tools: sharepoint_get_file_text.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "itemId": "01ABCDEF..." }

sharepoint_get_file_text

• Classification: read-only, medium-risk (content exposure).

• Use when: retrieving UTF-8 text from a known file.

• Do not use when: file is binary/large (prefer metadata or downstream export flow).

• Prerequisites: valid Graph token and readable file locator.

• Parameters: optional siteId, driveId, itemId, path; maxBytes? integer 1..1000000; optional userId/accessToken.

• Environment behavior: output redaction still applies but file payload may contain sensitive business data.

• Common failures: non-text content decoding, size limits, permission errors.

• Safety warning: avoid using broad maxBytes in production workflows unless downstream handling is controlled.

• Follow-up tools: none required; optionally token_rotation_config for long-running jobs.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "path": "Shared Documents/notes.txt", "maxBytes": 200000 }

sharepoint_create_folder

• Classification: mutating, high-risk.

• Use when: creating a folder in a known drive/location.

• Do not use when: you only need to inspect existing folders.

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters:

  • name: required non-empty string.

  • siteId?, driveId?, parentItemId?, parentPath?.

  • conflictBehavior?: rename|fail|replace.

  • userId?, accessToken?, authorizationKey?.

• Common failures: unresolved parent selector, unauthorized token, conflict behavior fail collisions.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "parentPath": "Shared Documents", "name": "Q4", "conflictBehavior": "rename", "authorizationKey": "<admin-key>" }

sharepoint_upload_file

• Classification: mutating, high-risk.

• Use when: uploading a new file under a known parent location.

• Do not use when: modifying content for an existing item id/path (use sharepoint_update_file).

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters:

  • fileName: required non-empty string.

  • One of contentText or contentBase64 is required.

  • siteId?, driveId?, parentItemId?, parentPath?, userId?, accessToken?, authorizationKey?.

• Common failures: missing content input, invalid base64 payloads, write permission denial.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "parentPath": "Shared Documents/Q4", "fileName": "notes.txt", "contentText": "hello", "authorizationKey": "<admin-key>" }

sharepoint_update_file

• Classification: mutating, high-risk.

• Use when: replacing file content for a known item id/path.

• Do not use when: only metadata changes are required.

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters:

  • One of itemId or path should be provided.

  • One of contentText or contentBase64 is required.

  • siteId?, driveId?, userId?, accessToken?, authorizationKey?.

• Common failures: unresolved target selector, missing content input, permission denial.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "itemId": "01ABCDEF...", "contentText": "updated", "authorizationKey": "<admin-key>" }

sharepoint_move_item

• Classification: mutating, high-risk.

• Use when: renaming and/or moving an item to a different parent.

• Do not use when: you need a duplicate instead of relocation (use sharepoint_copy_item).

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters:

  • itemId: required non-empty string.

  • At least one of newName or newParentItemId is required.

  • siteId?, driveId?, userId?, accessToken?, authorizationKey?.

• Common failures: invalid target parent id, permission denial, missing move intent fields.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "itemId": "01ABCDEF...", "newName": "notes-v2.txt", "authorizationKey": "<admin-key>" }

sharepoint_copy_item

• Classification: mutating, high-risk.

• Use when: copying a file/folder, optionally to a different parent/drive.

• Do not use when: you need in-place mutation.

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters:

  • itemId: required non-empty string.

  • Optional newName, targetDriveId, targetParentItemId.

  • siteId?, driveId?, userId?, accessToken?, authorizationKey?.

• Response behavior: Graph may return an async operation location header; response includes location when provided.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "itemId": "01ABCDEF...", "newName": "notes-copy.txt", "authorizationKey": "<admin-key>" }

sharepoint_delete_item

• Classification: mutating, high-risk.

• Use when: deleting a known item by id or path.

• Do not use when: soft-retention/audit policy requires archival first.

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters:

  • One of itemId or path should be provided.

  • siteId?, driveId?, userId?, accessToken?, authorizationKey?.

• Common failures: unresolved selector, permission denial, retention/lock constraints.

• Example: { "siteId": "contoso.sharepoint.com,abc,def", "itemId": "01ABCDEF...", "authorizationKey": "<admin-key>" }

connection_info

• Classification: read-only, low-risk.

• Use when: inspecting effective server/Vault/Postgres connectivity configuration.

• Do not use when: validating liveness (use healthcheck).

• Prerequisites: service is running.

• Parameters: none.

• Response data includes: server metadata, Vault connection info, Postgres host/port/db plus user/password presence markers.

• Common failures: startup misconfiguration.

• Example: {}

vault_connection_info

• Classification: read-only, low-risk.

• Use when: checking active Vault mode/address/namespace style details.

• Do not use when: validating actual secret read/write permission.

• Prerequisites: Vault client initialized.

• Parameters: none.

• Follow-up tools: healthcheck, get_secret.

• Example: {}

healthcheck

• Classification: read-only, low-risk.

• Use when: testing Postgres and Vault connectivity in one call.

• Do not use when: you need detailed service diagnostics.

• Prerequisites: Postgres and Vault reachable.

• Parameters: none.

• Expected data: { postgres: "ok", vault: "ok" }.

• Common failures: network, auth, or unavailable dependency.

• Example: {}

list_configs

• Classification: read-only, low-risk.

• Use when: auditing config keys by optional prefix and user scope.

• Do not use when: retrieving one exact key (use get_config).

• Prerequisites: Postgres available.

• Parameters: prefix? non-empty string, userId? non-empty string.

• Environment behavior: defaults to configured default user scope when omitted.

• Common failures: Postgres connectivity issues.

• Follow-up tools: get_config, set_config.

• Example: { "prefix": "vault.agent.", "userId": "default" }

get_config

• Classification: read-only, low-risk.

• Use when: reading one config value.

• Do not use when: you need all configs by namespace.

• Prerequisites: Postgres available.

• Parameters: key required non-empty string, userId?.

• Common failures: returns { ok:false, status:404 } when key missing in scope.

• Follow-up tools: set_config if key must be created/updated.

• Example: { "key": "token.rotation.intervalMs", "userId": "default" }

set_config

• Classification: mutating, medium-risk.

• Use when: creating/updating non-secret configuration.

• Do not use when: storing credentials/secrets (use Vault tools).

• Permissions: authorizationKey required when MCP_ADMIN_AUTH_KEY is configured.

• Prerequisites: Postgres write access.

• Parameters: key required, value required (unknown JSON type), optional userId, optional authorizationKey.

• Common failures: unauthorized key, Postgres write failures, invalid key formatting in callers.

• Safety warning: config changes can alter runtime behavior immediately for subsequent calls.

• Follow-up tools: get_config, list_configs.

• Example: { "key": "vault.agent.auth.mode", "value": "listener", "authorizationKey": "<admin-key>" }

delete_config

• Classification: mutating, high-risk.

• Use when: intentionally removing config overrides.

• Do not use when: you only want temporary behavior changes.

• Permissions: authorizationKey required when admin auth is enabled.

• Prerequisites: Postgres write access.

• Parameters: key required, optional userId, optional authorizationKey.

• Common failures: unauthorized, dependency/database errors.

• Safety warning: deletion can trigger fallback defaults and unexpected behavior shifts.

• Follow-up tools: get_config, token_rotation_config.

• Example: { "key": "vault.agent.listener.addr", "userId": "default", "authorizationKey": "<admin-key>" }

list_secrets

• Classification: read-only, medium-risk (metadata disclosure).

• Use when: discovering child keys under a Vault prefix.

• Do not use when: strict least-knowledge policy disallows key name visibility.

• Prerequisites: Vault list permission for prefix.

• Parameters: prefix? string.

• Expected data: { keys: string[] }.

• Common failures: Vault ACL denies list, path mount mismatch.

• Follow-up tools: get_secret.

• Example: { "prefix": "sharepoint/oauth/default" }

get_secret

• Classification: read-only, high-risk (secret material).

• Use when: controlled operational workflows need a Vault secret payload.

• Do not use when: only existence/listing is required.

• Prerequisites: Vault read permission on target path.

• Parameters: path required non-empty string.

• Common failures: returns { ok:false, status:404 } when missing; Vault ACL denial.

• Safety warning: treat output as sensitive even when redacted mode is active.

• Follow-up tools: set_secret, delete_secret.

• Example: { "path": "sharepoint/oauth/default/access-token" }

set_secret

• Classification: mutating, high-risk.

• Use when: writing structured secret values to Vault KV v2.

• Do not use when: persisting non-secret configuration.

• Permissions: authorizationKey required when admin auth is enabled.

• Prerequisites: Vault write permission.

• Parameters: path required; value required object (record<string, unknown>); optional authorizationKey.

• Common failures: unauthorized, invalid value shape for caller expectations, Vault write errors.

• Safety warning: overwrites stored secret content at target path.

• Follow-up tools: get_secret.

• Example: { "path": "service/api/key", "value": { "token": "***" }, "authorizationKey": "<admin-key>" }

delete_secret

• Classification: mutating, high-risk/destructive.

• Use when: rotating or decommissioning secret entries.

• Do not use when: you need rollback-safe updates (prefer versioned writes).

• Permissions: authorizationKey required when admin auth is enabled.

• Prerequisites: Vault delete permission.

• Parameters: path required non-empty string, optional authorizationKey.

• Common failures: unauthorized, Vault ACL denial, mount/path mismatch.

• Safety warning: destructive operation; verify path and backup policy before use.

• Follow-up tools: list_secrets, get_secret.

• Example: { "path": "service/api/key", "authorizationKey": "<admin-key>" }

vault_agent_token_read

• Classification: read-only, high-risk (token sink material).

• Use when: application workflows must inspect Vault Agent sink token data.

• Do not use when: ordinary health/config checks are sufficient.

• Permissions: authorizationKey required when admin auth is enabled.

• Prerequisites: Vault Agent sink path configured and readable.

• Parameters: optional authorizationKey.

• Common failures: unauthorized, missing token file, listener/file mode mismatch.

• Follow-up tools: token_lookup_self.

• Example: { "authorizationKey": "<admin-key>" }

token_lookup_self

• Classification: read-only, medium-risk.

• Use when: checking capabilities/TTL of the active Vault token.

• Do not use when: renewing or creating tokens.

• Permissions: authorizationKey required when admin auth is enabled.

• Prerequisites: valid Vault token context.

• Parameters: optional authorizationKey.

• Common failures: unauthorized, revoked/expired token context.

• Follow-up tools: token_renew_self.

• Example: { "authorizationKey": "<admin-key>" }

token_renew_self

• Classification: mutating, medium-risk.

• Use when: extending TTL for the current Vault token.

• Do not use when: token is non-renewable or policy prohibits renewals.

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters: optional increment (string duration), optional authorizationKey.

• Common failures: token non-renewable, max TTL reached, unauthorized.

• Follow-up tools: token_lookup_self.

• Example: { "increment": "1h", "authorizationKey": "<admin-key>" }

token_create

• Classification: mutating, high-risk.

• Use when: controlled issuance of scoped Vault child tokens.

• Do not use when: static token sharing would violate least privilege.

• Permissions: authorizationKey required when admin auth is enabled.

• Prerequisites: Vault policies and role setup.

• Parameters:

  • role_name?, policies?[], ttl?, period?, renewable?, explicit_max_ttl?, num_uses? (int >= 0), display_name?, meta? (record<string,string>), authorizationKey?.

• Common failures: policy mismatch, invalid TTL fields, ACL denial.

• Safety warning: overbroad token policies can create privilege escalation risk.

• Follow-up tools: token_lookup_self, token_revoke.

• Example: { "policies": ["default"], "ttl": "30m", "display_name": "mcp-child", "authorizationKey": "<admin-key>" }

token_revoke

• Classification: mutating, high-risk/destructive.

• Use when: revoking a known Vault token immediately.

• Do not use when: token identifier is uncertain.

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters: token required non-empty string; optional authorizationKey.

• Common failures: token already revoked/not found, ACL denial.

• Safety warning: destructive and immediate; can break active workloads.

• Follow-up tools: token_lookup_self (for current token context), operational health checks.

• Example: { "token": "hvs.xxxxx", "authorizationKey": "<admin-key>" }

token_revoke_self

• Classification: mutating, high-risk/destructive.

• Use when: intentionally terminating the current service token context.

• Do not use when: service must continue serving requests.

• Permissions: authorizationKey required when admin auth is enabled.

• Parameters: optional authorizationKey.

• Common failures: unauthorized, token already invalid.

• Safety warning: likely disrupts subsequent Vault operations until a new token is loaded.

• Follow-up tools: healthcheck, re-auth/token bootstrap workflow.

• Example: { "authorizationKey": "<admin-key>" }

vault_seed_http_token

• Classification: mutating, high-risk.

• Use when: provisioning HTTP bearer tokens in Vault token index.

• Do not use when: caller needs to supply an existing OAuth token (use vault_seed_oauth_token).

• Permissions: authorizationKey required when admin auth is enabled.

• Prerequisites: Vault write permission to token index path.

• Parameters:

  • userId?, tokenId?, scopes? (string or string[]), audience? (string or string[]), expiresAt? (string), path? (Vault path override), authorizationKey?.

• Environment behavior: index path defaults to configured value or app-derived fallback.

• Response data: includes generated token (only for this tool), tokenHash, indexPath, metadata fields.

• Common failures: unauthorized, path ACL denial, merge/write errors.

• Safety warning: generated token is credential material; handle output securely.

• Follow-up tools: token_lookup_self, HTTP auth tests.

• Example: { "userId": "default", "scopes": ["mcp:invoke"], "authorizationKey": "<admin-key>" }

vault_seed_oauth_token

• Classification: mutating, high-risk.

• Use when: storing externally issued OAuth access tokens in Vault index.

• Do not use when: you need the service to generate a new opaque bearer token.

• Permissions: authorizationKey required when admin auth is enabled.

• Prerequisites: Vault write permission and trusted token source.

• Parameters:

  • token required non-empty string.

  • Optional userId, tokenId, scopes (string or string[]), audience (string or string[]), expiresAt, path, authorizationKey.

• Response data: returns metadata and token hash, not the plaintext token.

• Common failures: unauthorized, invalid token input, Vault write errors.

• Safety warning: never log raw OAuth token in external systems.

• Follow-up tools: sharepoint_list_sites, sharepoint_connection_info.

• Example: { "token": "eyJ...", "userId": "default", "authorizationKey": "<admin-key>" }

token_rotation_config

• Classification: read-only, low-risk.

• Use when: inspecting effective rotation interval resolution.

• Do not use when: changing interval values (use set_config).

• Prerequisites: Postgres available for scoped overrides.

• Parameters: optional userId.

• Environment behavior: resolution order is user scope -> default scope -> env default.

• Common failures: Postgres access failures.

• Follow-up tools: get_config, set_config.

• Example: { "userId": "default" }

SharePoint Authentication

The SharePoint tools resolve a Microsoft Graph access token in this order:

1. accessToken argument on the tool call. This is useful for direct testing only.

2. SHAREPOINT_ACCESS_TOKEN environment variable.

3. Vault secret at SHAREPOINT_VAULT_ACCESS_TOKEN_PATH, defaulting to sharepoint/oauth/{userId}/access-token.

Vault token secrets may use any of these field names:

• access_token

• accessToken

• token

For FortisAI, prefer Vault storage and pass a server-controlled userId from the OpenAPI gateway or wrapper instead of letting arbitrary callers choose another user's token.

Security Behavior

• Sensitive fields are redacted unless MCP_ALLOW_SENSITIVE_OUTPUT=true.

• Mutating operations can be access controlled with MCP_ADMIN_AUTH_KEY.

• Vault write operations are serialized through an internal queue and retried with exponential backoff.

Environment Variables

Core:

• APP_NAME

• MCP_SERVER_NAME

• MCP_SERVER_VERSION

• MCP_ALLOW_SENSITIVE_OUTPUT

• MCP_ADMIN_AUTH_KEY

• MCP_TRANSPORT_MODE (stdio, http, or both)

• MCP_CONFIG_DEFAULT_USER_ID

• MCP_TOKEN_ROTATION_DEFAULT_INTERVAL_MS

• MCP_TOKEN_ROTATION_USER_INTERVAL_CONFIG_KEY

• MCP_VAULT_AGENT_AUTH_MODE_CONFIG_KEY

• MCP_VAULT_AGENT_TOKEN_FILE_PATH_CONFIG_KEY

• MCP_VAULT_AGENT_LISTENER_ADDR_CONFIG_KEY

HTTP transport:

• MCP_HTTP_HOST

• MCP_HTTP_PORT

• MCP_HTTP_PATH

• MCP_HTTP_HEALTH_PATH

• MCP_HTTP_AUTH_MODE (token, oauth2, both)

• MCP_HTTP_TOKEN_SOURCE (vault, env)

• MCP_HTTP_AUTH_TOKENS (comma-separated bearer tokens)

• MCP_HTTP_TRUST_PROXY

• MCP_HTTP_ALLOWED_ORIGINS (comma-separated)

• MCP_HTTP_ALLOWED_IPS (comma-separated)

• MCP_HTTP_MAX_BODY_BYTES

• MCP_HTTP_RATE_LIMIT_WINDOW_MS

• MCP_HTTP_RATE_LIMIT_MAX_REQUESTS

• MCP_HTTP_VAULT_TOKEN_INDEX_PATH

• MCP_HTTP_VAULT_TOKEN_DEFAULT_USER_ID

• MCP_HTTP_VAULT_TOKEN_REQUIRED_SCOPES

• MCP_HTTP_VAULT_TOKEN_REQUIRED_AUDIENCE

• MCP_HTTP_VAULT_TOKEN_CACHE_TTL_MS

• MCP_HTTP_OAUTH2_INTROSPECTION_URL

• MCP_HTTP_OAUTH2_CLIENT_ID

• MCP_HTTP_OAUTH2_CLIENT_SECRET

• MCP_HTTP_OAUTH2_REQUIRED_SCOPES

• MCP_HTTP_OAUTH2_REQUIRED_AUDIENCE

• MCP_HTTP_OAUTH2_TIMEOUT_MS

• MCP_HTTP_OAUTH2_CACHE_TTL_MS

• MCP_HTTP_TLS_ENABLED

• MCP_HTTP_TLS_CERT_PATH

• MCP_HTTP_TLS_KEY_PATH

Postgres:

• POSTGRES_HOST

• POSTGRES_PORT

• POSTGRES_EXPOSED_PORT (host-exposed Docker port; default 5432)

• POSTGRES_DB

• POSTGRES_USER

• POSTGRES_PASSWORD

Postgres config model:

• Configuration data is multi-user scoped in sharepoint_config using composite key (user_id, key).

• MCP config tools accept optional userId; when omitted, MCP_CONFIG_DEFAULT_USER_ID is used.

• Seed records include:

  • default/sharepoint.feature

  • default/app.defaults for future default parameters.

  • default/token.rotation.intervalMs

  • default/vault.agent.auth.mode

  • default/vault.agent.tokenFilePath

  • default/vault.agent.listener.addr

SharePoint:

• SHAREPOINT_GRAPH_BASE_URL

• SHAREPOINT_DEFAULT_USER_ID

• SHAREPOINT_ACCESS_TOKEN

• SHAREPOINT_VAULT_ACCESS_TOKEN_PATH

• SHAREPOINT_TIMEOUT_MS

• SHAREPOINT_MAX_RESPONSE_CHARS

Vault:

• VAULT_ADDR

• VAULT_EXPOSED_PORT (host-exposed Docker port; default 8200)

• VAULT_CLUSTER_EXPOSED_PORT (host-exposed Docker port for cluster listener in production compose; default 8201)

• VAULT_TOKEN

• VAULT_AGENT_ENABLED

• VAULT_AGENT_AUTH_MODE (none, file, listener, both)

• VAULT_AGENT_TOKEN_FILE_PATH

• VAULT_AGENT_LISTENER_ENABLED

• VAULT_AGENT_LISTENER_ADDR

• VAULT_UNSEAL_KEY

• VAULT_KV_MOUNT

• VAULT_WRITE_RETRY_ATTEMPTS

• VAULT_WRITE_RETRY_BASE_DELAY_MS

• VAULT_WRITE_RETRY_MAX_DELAY_MS

Compose-exposed HTTP:

• MCP_HTTP_EXPOSED_PORT (host-exposed Docker port for mcp-http; default 3000)

Naming defaults:

• APP_NAME defaults to sharepoint.

• The Postgres config table defaults to ${APP_NAME}_config.

• The Vault token index path defaults to ${APP_NAME}/http/auth/token-index.

• Set only APP_NAME to rename the app-scoped Vault/Postgres schema across local and external stores.

Reference values are in .env.example.

Quick Start

1. Install dependencies.

2. Copy .env.example to .env.

3. Start local services with docker compose up -d.

4. Resolve the managed unseal key: npm run vault:unseal-key -- --json.

5. Initialize and unseal local Vault (first run):

docker exec -e VAULT_ADDR=http://127.0.0.1:8200 sharepoint-mcp-vault vault operator init -key-shares=1 -key-threshold=1 -format=json
docker exec -e VAULT_ADDR=http://127.0.0.1:8200 sharepoint-mcp-vault vault operator unseal <unseal_key_from_init_or_env>

6. Seed a test secret in Vault.

7. Start the MCP server with npm start.

8. Run tests with npm test.

External Services Mode

Use this mode when Vault and Postgres are already managed outside this repository.

Required environment variables:

• POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD

• VAULT_ADDR, VAULT_TOKEN

Run the app-only compose stack:

docker compose -f docker-compose.external.yml up -d

Notes:

• The app still uses Vault for secrets and Postgres for config.

• The external stack is the same MCP HTTP container, but it skips local Postgres/Vault containers.

• If you keep Vault sealed, the app will still require whatever unseal process your external Vault uses.

Test Coverage Notes

Current automation includes listener-related coverage for Vault Agent runtime resolution.

• tests/vault-agent-runtime.test.js validates:

  • listener mode resolution from Postgres defaults

  • both mode resolution (listener + file)

  • fallback to environment values when database mode is invalid

Transport scripts:

# stdio only (default)
npm run start:stdio

# HTTP transport only
npm run start:http

# run stdio + HTTP as two processes
npm run start:both

License

This project is licensed under the MIT License. See LICENSE.

HTTP MCP Endpoint

Default endpoint values:

• MCP URL: http://127.0.0.1:3000/mcp

• Health URL: http://127.0.0.1:3000/healthz

HTTP transport security controls:

• Every /mcp request requires Authorization: Bearer <token>.

• For MCP_HTTP_AUTH_MODE=token, set MCP_HTTP_TOKEN_SOURCE=vault to validate tokens from Vault.

• For MCP_HTTP_AUTH_MODE=oauth2, bearer tokens are validated by OAuth2 introspection.

• For MCP_HTTP_AUTH_MODE=both, either token strategy can authorize requests.

• Mutating tools still require authorizationKey when MCP_ADMIN_AUTH_KEY is set.

• Request limits are enforced with:

  • MCP_HTTP_MAX_BODY_BYTES

  • MCP_HTTP_RATE_LIMIT_WINDOW_MS

  • MCP_HTTP_RATE_LIMIT_MAX_REQUESTS

• Optional network restrictions:

  • MCP_HTTP_ALLOWED_ORIGINS

  • MCP_HTTP_ALLOWED_IPS

Vault Multi-User Token Model

Store HTTP bearer tokens in Vault at MCP_HTTP_VAULT_TOKEN_INDEX_PATH.

Default-user fallback behavior:

• MCP_HTTP_VAULT_TOKEN_DEFAULT_USER_ID defaults to default.

• If no non-default users exist in the token index, the default user is always used as fallback.

Supported index shape:

{
	"tokens": {
		"<sha256(token)>": {
			"userId": "user-123",
			"tokenId": "tok-123",
			"active": true,
			"scopes": ["mcp:invoke", "mcp:read"],
			"audience": ["codex", "claude"],
			"expiresAt": "2026-12-31T23:59:59Z"
		}
	}
}

Notes:

• Store only token hashes in Vault index data, never plaintext tokens.

• MCP_HTTP_VAULT_TOKEN_REQUIRED_SCOPES and MCP_HTTP_VAULT_TOKEN_REQUIRED_AUDIENCE enforce policy checks.

• This keeps secrets in Vault under the app-prefixed root while configuration remains in the app-prefixed Postgres table.

Vault HTTP Token Seeding

Use the helper script to generate an opaque bearer token and store it in the Vault user token structure:

npm run vault:seed-http-token -- --user-id default --json

Useful options:

• --user-id <id>: Vault user to seed.

• --token-id <id>: Optional token id stored with the entry.

• --scopes <list>: Comma or space separated scopes.

• --audience <list>: Comma or space separated audience values.

• --expires-at <value>: Optional ISO timestamp or unix seconds.

• --path <vault-path>: Override the token index path.

The script writes the token record under the app-prefixed user structure and mirrors the token in the top-level token map for compatibility.

If you need to reseed a user, run the script again with the same --user-id and a new --token-id.

Vault OAuth Token Seeding

Use the helper script to store a provided OAuth access token in the Vault user token structure:

npm run vault:seed-oauth-token -- --token "$OAUTH_ACCESS_TOKEN" --user-id default --json

Useful options:

• --token <value>: OAuth access token to seed.

• --user-id <id>: Vault user to seed.

• --token-id <id>: Optional token id stored with the entry.

• --scopes <list>: Comma or space separated scopes.

• --audience <list>: Comma or space separated audience values.

• --expires-at <value>: Optional ISO timestamp or unix seconds.

• --path <vault-path>: Override the token index path.

The script stores the provided token under the app-prefixed user structure, keeps the top-level token map aligned, and marks the entry as oauth2 in Vault metadata.

MCP Tool

The same capability is exposed as an MCP tool for controlled setup workflows:

• vault_seed_http_token: generate a bearer token and store it in the Vault HTTP token index for a user.

• vault_seed_oauth_token: store a provided OAuth access token in the Vault HTTP token index for a user.

The tool requires authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

Vault Token Lifecycle MCP Tools

The server exposes node-vault token lifecycle methods as MCP tools:

• token_lookup_self -> tokenLookupSelf

• token_renew_self -> tokenRenewSelf

• token_create -> tokenCreate

• token_revoke -> tokenRevoke

• token_revoke_self -> tokenRevokeSelf

These tools are intended for controlled operational usage and are guarded by admin authorization when MCP_ADMIN_AUTH_KEY is configured.

Vault Agent Auto-Auth and Token Renewal

Vault Agent can own token auth/renewal while this service reads the sink token file.

• Enable with VAULT_AGENT_ENABLED=true

• Choose auth mode with VAULT_AGENT_AUTH_MODE:

  • file: use Vault Agent token sink file

  • listener: use Vault Agent listener endpoint

  • both: enable listener operations and file-based token read workflows

• Configure sink file path with VAULT_AGENT_TOKEN_FILE_PATH

• Enable listener with VAULT_AGENT_LISTENER_ENABLED=true

• Configure listener with VAULT_AGENT_LISTENER_ADDR

• Use vault_agent_token_read when application workflows need token sink visibility

When Vault Agent mode is enabled:

• File mode refreshes token state from the configured token sink path.

• Listener mode routes Vault operations through the configured Vault Agent listener.

• Both mode supports listener operations and token sink read workflows.

Option 3: Postgres-Backed Non-Secret Vault Agent Settings

This server supports storing non-secret Vault Agent runtime pointers/settings in Postgres while keeping token material in Vault.

• Runtime settings are read from default user config scope (MCP_CONFIG_DEFAULT_USER_ID).

• Key names are configurable with:

  • MCP_VAULT_AGENT_AUTH_MODE_CONFIG_KEY

  • MCP_VAULT_AGENT_TOKEN_FILE_PATH_CONFIG_KEY

  • MCP_VAULT_AGENT_LISTENER_ADDR_CONFIG_KEY

• Recommended values in Postgres:

  • vault.agent.auth.mode

  • vault.agent.tokenFilePath

  • vault.agent.listener.addr

Rotation Time Configuration

Rotation interval supports both global defaults and user-scoped overrides:

• Global default env variable: MCP_TOKEN_ROTATION_DEFAULT_INTERVAL_MS

• User-scoped config key name: MCP_TOKEN_ROTATION_USER_INTERVAL_CONFIG_KEY (default token.rotation.intervalMs)

Effective value resolution is:

1. User-scoped Postgres config (userId + key)

2. Default user Postgres config (default + key)

3. Global env default

Use token_rotation_config tool to inspect the resolved rotation interval for a user scope.

Minimal remote call example:

curl -i http://127.0.0.1:3000/mcp \
	-H "Authorization: Bearer replace-me-token" \
	-H "Accept: application/json, text/event-stream" \
	-H "Content-Type: application/json" \
	-d '{
		"jsonrpc": "2.0",
		"id": 1,
		"method": "initialize",
		"params": {
			"protocolVersion": "2025-11-25",
			"capabilities": {},
			"clientInfo": { "name": "client", "version": "1.0.0" }
		}
	}'

HTTPS Deployment Choice

This repository uses a reverse proxy (recommended): terminate TLS at a reverse proxy or load balancer.

• Keep this app on internal HTTP.

• Enforce HTTPS, client allowlists, and edge-level controls at the proxy/LB.

• Forward traffic to MCP_HTTP_HOST:MCP_HTTP_PORT.

• Keep MCP_HTTP_TLS_ENABLED=false in this process mode.

Popular patterns include Nginx, Traefik, Envoy, ALB/NLB, or Cloudflare Tunnel in front of /mcp.

Vault Production Migration (Raft)

The repository now includes a Vault production migration scaffold under vault-production:

• vault-production/config/vault.hcl: Raft-backed Vault server configuration.

• vault-production/docker-compose.vault-prod.yml: Compose definition for Vault in server mode (non-dev).

• vault-production/scripts/convert-dev-to-prod.sh: Script to export dev KV data, start Raft Vault, initialize/unseal, and import secrets.

• vault-production/scripts/bootstrap-post-conversion.sh: Script to enable audit, write policy, configure AppRole, and emit service credentials.

• scripts/vault-unseal-key.js: Script to resolve unseal key from VAULT_UNSEAL_KEY or src/config/vault.unseal.key.json.

• vault-production/README.md: Detailed migration notes and options.

Managed unseal key flow:

• VAULT_UNSEAL_KEY is optional and can be injected at runtime.

• If VAULT_UNSEAL_KEY is not set, npm run vault:unseal-key reads src/config/vault.unseal.key.json.

• If the key file is missing or empty, a 24-character key is generated and saved to src/config/vault.unseal.key.json.

• Both compose stacks run a one-shot vault-unseal-key-init service before Vault startup to ensure key material exists.

Run the conversion:

bash vault-production/scripts/convert-dev-to-prod.sh --init-keys-out vault-production/backups/vault-init.json

Common options:

# Use a different KV mount
bash vault-production/scripts/convert-dev-to-prod.sh --mount secret

# Migrate infra only (skip data movement)
bash vault-production/scripts/convert-dev-to-prod.sh --skip-export --skip-import

# Use when Raft Vault is already initialized
bash vault-production/scripts/convert-dev-to-prod.sh --skip-init

# Explicitly set key file path used by convert script
bash vault-production/scripts/convert-dev-to-prod.sh --unseal-key-path src/config/vault.unseal.key.json

# Post-conversion hardening bootstrap (audit, policy, AppRole)
bash vault-production/scripts/bootstrap-post-conversion.sh --vault-token <root_or_admin_token>

# CI-friendly machine output
bash vault-production/scripts/bootstrap-post-conversion.sh \
	--vault-token <root_or_admin_token> \
	--output json

VS Code Agent Structure

This repository includes a project agent structure for adapting this MCP server to additional service-backed MCP implementations:

• agent/README.md: Overview of agent assets.

• agent/playbooks/service-onboarding.md: Step-by-step onboarding checklist.

• agent/templates/service-spec.md: Request template for describing new service integrations.

Workspace custom agent:

• .github/agents/sharepoint-services-mcp.agent.md

• .github/prompts/adapt-sharepoint-service.prompt.md

Use this custom agent when you want GitHub Copilot in VS Code to:

1. Configure new service adapters under src/services.

2. Register matching MCP tools in src/mcp/server.js.

3. Update env validation in src/config/env.js.

4. Preserve authorization and redaction behavior.

5. Add tests and documentation updates.

Test Coverage

Integration tests in tests/server.integration.test.js cover:

• Healthcheck behavior

• Authorization on mutating tools

• Redaction behavior for secret output

HTTP transport tests in tests/http.integration.test.js cover:

• Unauthorized requests are rejected

• Authorized MCP initialization succeeds

• Internal failures return JSON-RPC-compatible error responses

• Health endpoint behavior

Vault token auth tests in tests/vault-token-auth.test.js cover:

• Multi-user token index lookup by SHA-256 hash

• Inactive token rejection

• Scope/audience-aware authorization inputs

Production migration tests in tests/vault-production.test.js cover:

• Presence of Vault production scaffold files

• Raft config expectations

• Non-dev Vault compose command validation

• Conversion/bootstrap script help and bash syntax checks

Extend The Server

1. Add domain services under src/services.

2. Register new tools in src/mcp/server.js.

3. Add corresponding tests under tests.

4. Keep mutating tools behind authorization checks.

5. Keep secret-bearing fields redacted by default.

Notes

• docker-compose.yml now runs Vault with Raft-backed storage for local persistence.

• The managed key script is an automation helper and not a Vault KMS/HSM auto-unseal backend.

• The migration scaffold starts with bootstrap-friendly defaults and still requires TLS, production auth methods, and credential rotation before real production use.