feat(mcp-server): agentUrl option to route MCP tool calls internally

[Scra3]

Context

MCP tools don't touch the datasource directly — each tool call (list, create, executeAction…) calls back into the agent's data layer over HTTP via agent-client. The URL used is the environment's public api_endpoint (as registered in Forest), read from AuthInfo.extra.environmentApiEndpoint.

Consequence: even when the MCP server is mounted inside the agent (same process), every tool call leaves over the public internet and comes back. A self-hosted customer (Swaive, KYB prod use case with n8n) asked to keep this traffic on their private network.

Change

Opt-in agentUrl option that overrides only the internal tool→agent channel:

agent.mountAiMcpServer({ agentUrl: 'http://forest-agent.internal:3310' });

• forest-oauth-provider.ts — new agentUrl (validated as an absolute URL, trailing slash stripped); verifyAccessToken puts agentUrl ?? environmentApiEndpoint into extra.environmentApiEndpoint (the single consumer, in agent-caller.ts). getBaseUrl() untouched.
• server.ts — ForestMCPServerOptions.agentUrl, threaded to the provider.
• cli.ts — FOREST_AGENT_URL env var for the standalone binary.
• agent.ts — mountAiMcpServer({ agentUrl }) threading.

The advertised OAuth URLs (issuer, .well-known metadata, authorize/token) stay public — external MCP clients (n8n) still authenticate from outside. agentUrl only changes where tools reach the agent.

Same concept and name as addWorkflowExecutor({ agentUrl }). Default unchanged (public api_endpoint), so zero impact on existing deployments.

Tests

• forest-oauth-provider.test.ts — extra.environmentApiEndpoint = agentUrl when set (fallback to api_endpoint otherwise), trailing slash stripped, invalid URL throws.
• server.test.ts — with agentUrl set, advertised OAuth metadata URLs stay public.
• agent.test.ts — mountAiMcpServer({ agentUrl }) reaches ForestMCPServer.

mcp-server: 608 tests pass, lint clean.

Definition of Done

General

• Explicit title following Conventional Commits
• Test manually the implemented changes
• Validate the code quality

Security

• Consider the security impact — agentUrl is validated; default behavior unchanged; the option improves security posture (keeps tool traffic off the public internet).

🤖 Generated with Claude Code

Note

Add agentUrl option to ForestMCPServer to route MCP tool calls to a self-hosted agent

• Adds an optional agentUrl to ForestMCPServerOptions and ForestOAuthProvider that, when set, overrides the public api_endpoint embedded in OAuth tokens as the tool callback base URL.
• Exposes the option through Agent.mountAiMcpServer (stored and forwarded on Agent.start) and through the CLI via the FOREST_AGENT_URL environment variable.
• ForestOAuthProvider.normalizeAgentUrl validates that the value is an absolute http/https URL with no query string or fragment, and strips trailing slashes; invalid values throw at construction time.
• OAuth metadata URLs are unaffected by agentUrl — only the per-token environmentApiEndpoint changes.
• Risk: passing an invalid agentUrl now throws during ForestOAuthProvider construction, which is a new failure mode for existing callers that forward arbitrary user input.

^{Macroscope summarized c476514.}

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (3)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/agent.ts	100.0%
	packages/mcp-server/src/forest-oauth-provider.ts	100.0%
	packages/mcp-server/src/server.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.