feat: add /v1/orchestrations for server-side MCP tool execution

[claytonlin1110]

Summary

This adds a new local API endpoint POST /v1/orchestrations that brings desktop-like tool execution to headless API clients: it loads assistant_id settings, runs a tool-calling loop, executes MCP tools on the server, and returns the final completion.

Fixes Issues

• Closes idea: Headless Orchestration API — Accessing Projects, Assistants, and MCP Tools via API #7789

Self Checklist

• Added relevant comments, esp in complex areas
• Updated docs (for bug fixes / features)
• Created issues for follow-up changes or refactoring needed

[claytonlin1110]

Hi, @louis-jan
Would you please review my first contribution?
Thank you

[louis-jan]

@claytonlin1110 can you help elaborate how it works in these cases:

• Client provides tools from their side. There is a mixed of server side and client side tools.
• How client approves / denies server tool executions?

[louis-jan]

Another thought is that, clients suppose to work with chat/completions endpoint. So it could be a setting on GUI then clients don't have to support new endpoint?

[claytonlin1110]

• Client provides tools from their side. There is a mixed of server side and client side tools.

/v1/orchestrations only exposes MCP (server) tools to the model ; client-provided tools aren’t merged in yet. To support a mix, we'd union tool schemas, then route each tool_call: run MCP on the server, or return pending calls / accept client tool results on the next round.

• How client approves / denies server tool executions?

The desktop UI can ask the user before calling MCP; that’s frontend, not the HTTP endpoint. /v1/orchestrations auto-executes MCP tool calls (no approval step). To add approval over the API, we'd need something like a two-phase flow (return tool calls -> client approves -> server runs) or server policy (allowlist / auto_execute: false).

[claytonlin1110]

Another thought is that, clients suppose to work with chat/completions endpoint. So it could be a setting on GUI then clients don't have to support new endpoint?

Yes. we can add a Settings toggle and a Jan-only field on POST /v1/chat/completions (e.g. jan_execute_tools: true). The local proxy would run server-side MCP orchestration and still return a normal chat completion; clients don’t need a new endpoint. The field should be handled only by Jan’s proxy and not forwarded to upstream providers. /v1/orchestrations can stay optional for scripts.

[claytonlin1110]

@louis-jan

[louis-jan]

That would be great @claytonlin1110 can you help me add this to chat/completions

[louis-jan]

@claytonlin1110 help me fix the build errors, will test after this

[claytonlin1110]

@louis-jan Please re-run CI

[louis-jan]

@claytonlin1110 can we make assistant_id optional? Context: As a user I want to make request to v1/orchestrations to have tools executed from server side, but I don't want and don't know how to put assistant_id in the payload. E.g. assistant id is not exposed on the GUI?

[claytonlin1110]

@louis-jan
assistant_id is optional now. It's only needed if you want assistant-specific instructions/model hint. For basic headless orchestration, users can just send messages (and optionally model) without knowing any assistant id

[louis-jan]

Works great to me

[markmehere]

Secretly was following this and glad it got in.

It'd be nice to have the MCP whitelisting sooner rather than later. I'm hoping we can have a list of enabled MCPs for the local Jan user and a separate list for the orchestration. So I can stop randoms burning my Exa tokens, but they can have as many time-of-day reports as they want.

I also think we need an /assistants end-point which is something I've been planning for ages so we can list out the assistant IDs for orchestrations.

Good work either way!