feat(api): add readonly connectors API #4258

jaideepr97 · 2025-11-28T17:57:09Z

What does this PR do?

Adds a new API for connectors and MCP registry support along with required types.
Does not include any implementation for it

Closes #4235 and #4061 (partially)

Test Plan

no tests included

cdoern

this looks like its on the right path, but might conflict with #4191 , @leseb wdyt the order of operations should be here?

jaideepr97 · 2025-12-01T15:17:35Z

this looks like its on the right path, but might conflict with #4191 , @leseb wdyt the order of operations should be here?

thanks for calling this out! I did see this PR as well, though it looks like @leseb has taken care to make his PR backward compatible, so maybe (hopefully) they shouldn't break each other?

leseb · 2025-12-01T15:20:08Z

this looks like its on the right path, but might conflict with #4191 , @leseb wdyt the order of operations should be here?

Would love to see this being written as a FastAPI Router since that's the new way moving fw. I think #4191 is pretty ready, but since it's not merged I think that 4258 PR should stay as is and we will convert it later since we can maintain both router and non-router.

jaideepr97 · 2025-12-01T15:46:50Z

this looks like its on the right path, but might conflict with #4191 , @leseb wdyt the order of operations should be here?

Would love to see this being written as a FastAPI Router since that's the new way moving fw. I think #4191 is pretty ready, but since it's not merged I think that 4258 PR should stay as is and we will convert it later since we can maintain both router and non-router.

ack, I think that makes sense
happy to work on a follow up PR to port this to router post merge

github-actions · 2025-12-01T19:25:47Z

✱ Stainless preview builds

This PR will update the llama-stack-client SDKs with the following commit message.

feat(api): add readonly connectors API

Edit this comment to update it. It will appear in the SDK's changelogs.

⚠️

llama-stack-client-node studio · code · diff

There was a regression in your SDK.
generate ⚠️ → build ✅ → lint ✅ → test ✅
npm install https://pkg.stainless.com/s/llama-stack-client-node/84dcaf181be4867372ad49f296f8735318702dc4/dist.tar.gz
New diagnostics (4 warning)

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}/tools/{tool_name}` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}/tools` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️

llama-stack-client-kotlin studio · code · diff

There was a regression in your SDK.
generate ⚠️ → lint ✅ → test ❗

New diagnostics (4 warning)

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}/tools/{tool_name}` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}/tools` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️

llama-stack-client-python studio · code · diff

There was a regression in your SDK.
generate ⚠️ → build ⏳ → lint ⏳ → test ⏳

New diagnostics (4 warning, 1 note)

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}/tools/{tool_name}` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}/tools` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

💡 Model/NeedsRename: Consider renaming model `file`; e.g. `api_file`'

⚠️

llama-stack-client-go studio · code · diff

There was a regression in your SDK.
generate ⚠️ → lint ❗ → test ❗
go get github.com/stainless-sdks/llama-stack-client-go@90c63ea2b4778c6926796289f224fbec8c240373
New diagnostics (4 warning)

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}/tools/{tool_name}` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors/{connector_id}/tools` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

⚠️ Endpoint/NotConfigured: `get /v1alpha/connectors` exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
Last updated: 2025-12-10 17:27:26 UTC

ashwinb · 2025-12-01T23:13:20Z

Stainless warnings above ^ you need to update client-sdks/stainless/config.yml accordingly to add a new connectors sub-resource. Note that it should be under the alpha resource.

src/llama_stack_api/registries.py

ashwinb

I think we should only do Connectors for now without Registries.

src/llama_stack_api/resource.py

ashwinb · 2025-12-02T05:34:05Z

src/llama_stack_api/connectors.py

+        default=None, alias="connector_id", description="User-specified identifier for the connector"
+    )
+    url: str = Field(..., description="URL of the connector")
+    created_at: datetime = Field(..., description="Timestamp of creation")


it's surprising these two fields aren't tracked in Resource -- or are they?

I don't think they are
https://github.com/llamastack/llama-stack/blob/main/src/llama_stack_api/resource.py#L25

could we add these fields to all resources instead? it could be a separate PR..

update - i realized it would take more work than I thought to move these timestamps to the base resource class
so instead, i have only removed it from here for now and will make a separate PR later

ashwinb · 2025-12-02T05:36:46Z

src/llama_stack_api/connectors.py

+    server_description: str | None = Field(default=None, description="Description of the server")
+    # TODO: using ToolDef for now, but MCPListToolsTool should probably be updated and used instead
+    # once toolgroups are removed completely
+    tools: list[ToolDef] | None = Field(default=None, description="List of tools available from the connector")


why not use MCPListToolsTool as the comment indicates? but more importantly, I don't think we should persist tools at all? The Stack should list tools dynamically and cache the list for what could be a reasonable period of time. I think the MCP protocol is explicitly about being able to discover tools dynamically. Am I mistaken?

why not use MCPListToolsTool as the comment indicates?

I was using it initially, but then I saw ToolDef is more comprehensive including output_schema and metadata (which are missing in MCPListToolsTool) also the utility function to list MCP server tools also returns a list of ToolDefs, so I chose to stay with it for now until toolgroups and related types are removed completely

I don't think we should persist tools at all? The Stack should list tools dynamically and cache the list for what could be a reasonable period of time. I think the MCP protocol is explicitly about being able to discover tools dynamically. Am I mistaken?

I am not too familiar with the specific intentions expressed in the protocol itself so I can't speak to that, but I only included this here because I had initially proposed 2 separate endpoints to list all available connectors and all available tools. I got feedback that these could be combined into a single endpoint so I inlcude an include_tools filter and needed to store the tools somewhere

However, we already have the ability to list tools only for specific connector_ids when requested, which can be done dynamically without storing them in the connector object, so if we are okay with not listing a connector's tools along with all its other information, I can remove this field from the connector

removed the persistence of tools in connector, and added authorization to the query params for the endpoints that will return tool list or individual tools

src/llama_stack_api/connectors.py

ashwinb · 2025-12-02T05:39:09Z

src/llama_stack_api/connectors.py

+    connector_type: ConnectorType = Field(default=ConnectorType.MCP)
+    connector_id: str | None = Field(default=None, description="Unique identifier for the connector")
+    url: str = Field(..., description="URL of the connector")
+    headers: dict[str, Any] | None = Field(default=None, description="HTTP headers to include when connecting")


how come the other fields (server_*, etc.) from Connector aren't present here?

I can include the server_label here, the other fields can be queried from the server itself so user doesn't have to provide them

added server_label to connector input

I think we should have ConnectorInput mirror very closely to Connector -- at least as long as Connector inherits from Resource. Why? Because that is what goes into the registry. Auxiliary state (like tools, other attributes about the server) which would be queried by the server at least at startup should be kept separately and only in memory. It might be reasonable to split the "connector datatype which gets stored in registry db" from the "connector datatype which is returned when you query in the API, especially if you want the auxilliary state to be provided"

It might be reasonable to split the "connector datatype which gets stored in registry db" from the "connector datatype which is returned when you query in the API,

Sure, I like this. I will update connector input to include everything except maybe server name and description. Those can remain as API object fields and move the timestamp ones to the base resource class

ashwinb · 2025-12-03T20:15:45Z

src/llama_stack_api/connectors.py

+        default=None, alias="connector_id", description="User-specified identifier for the connector"
+    )
+    url: str = Field(..., description="URL of the connector")
+    created_at: datetime = Field(..., description="Timestamp of creation")


could we add these fields to all resources instead? it could be a separate PR..

ashwinb · 2025-12-03T20:19:31Z

src/llama_stack_api/connectors.py

+    connector_type: ConnectorType = Field(default=ConnectorType.MCP)
+    connector_id: str | None = Field(default=None, description="Unique identifier for the connector")
+    url: str = Field(..., description="URL of the connector")
+    headers: dict[str, Any] | None = Field(default=None, description="HTTP headers to include when connecting")


I think we should have ConnectorInput mirror very closely to Connector -- at least as long as Connector inherits from Resource. Why? Because that is what goes into the registry. Auxiliary state (like tools, other attributes about the server) which would be queried by the server at least at startup should be kept separately and only in memory. It might be reasonable to split the "connector datatype which gets stored in registry db" from the "connector datatype which is returned when you query in the API, especially if you want the auxilliary state to be provided"

ashwinb · 2025-12-03T20:20:50Z

src/llama_stack_api/connectors.py

+    url: str = Field(..., description="URL of the connector")
+    server_label: str | None = Field(default=None, description="Label of the server")
+    headers: dict[str, Any] | None = Field(default=None, description="HTTP headers to include when connecting")
+    authorization: str | None = Field(default=None, description="OAuth access token for authentication")


is that a good idea to keep this unencrypted in a run.yaml even in an enterprise world? stuff like this is almost always a Secret

I included this here with the intention that stack admins can set auth tokens etc in env vars and references those vars in the run.yaml, then the stack can resolve them
The only reason for allowing admins to configure auth in the first place is if we want to handle cases where we want to enable users to access infra-owned MCP servers that they won't have their own credentials for. In such cases, maybe a stack admin will need to put some creds in place that can be used for this purpose.
I am not 100% sure how realistic this scenario would be - for most use cases where we expect users to bring their own auth tokens we can remove this field from the connector input altogether I think

thoughts?

@jaideepr97 the scenario is quite reasonable but the mechanism is not. auth tokens like these should never be in plain text and so need to be read via some kind of Secrets reading mechanism. the Stack currently does not have in built support to tie into things like the AWS SecretsManager, etc. so I suggest we just not have it for now.

makes sense, removed them

leseb · 2025-12-04T14:51:42Z

FYI #4191 merged so it'd be nice to have this added a router :)

jaideepr97 · 2025-12-04T17:12:00Z

FYI #4191 merged so it'd be nice to have this added a router :)

@leseb that's awesome. Given that there is limited time to get stuff merged for the 0.4.0 release, I am inclined to try and get this merged as is for now so that this functionality at least exists in 0.4.0
I am happy to port it to router after the fact, rather than add another few rounds of review to this PR and risk missing the release

Does that work?

ashwinb · 2025-12-04T22:24:20Z

src/llama_stack_api/connectors.py

+
+
+@json_schema_type
+class ConnectorInput(BaseModel):


I wonder if we can share common attributes between Connector and ConnectorInput via a shared BaseModel?

jaideepr97 · 2025-12-05T17:30:10Z

@ashwinb Any idea why this particular integration test keeps failing consistently? Seems unrelated to the PR itself

mattf · 2025-12-08T15:34:19Z

@ashwinb Any idea why this particular integration test keeps failing consistently? Seems unrelated to the PR itself

hopefully #4335

jaideepr97 · 2025-12-08T15:57:50Z

@ashwinb Any idea why this particular integration test keeps failing consistently? Seems unrelated to the PR itself

hopefully #4335

gotcha, thanks for the pointer! that should do it 🤞

Closes llamastack#4235 and llamastack#4061 (partially) Signed-off-by: Jaideep Rao <[email protected]>

… info from connectors api response Signed-off-by: Jaideep Rao <[email protected]>

Signed-off-by: Jaideep Rao <[email protected]>

ashwinb · 2025-12-10T18:43:18Z

src/llama_stack_api/connectors.py

+    :param type: Type of resource, always 'connector' for connectors
+    :param connector_type: Type of connector (e.g., MCP)
+    :param connector_id: Identifier for the connector
+    :param url: URL of the connector


this documentation is no longer in sync

ashwinb · 2025-12-10T18:45:39Z

src/llama_stack_api/connectors.py

+    async def get_connector(
+        self,
+        connector_id: str,
+        authorization: str | None = None,


why is there an authorization parameter here?

jaideepr97 requested review from ashwinb, bbrowning, cdoern, ehhuang, franciscojavierarceo, leseb, mattf and raghotham as code owners November 28, 2025 17:57

meta-cla bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 28, 2025

jaideepr97 changed the title ~~feat: add connectors API~~ feat: add readonly connectors API Nov 28, 2025

jaideepr97 mentioned this pull request Nov 28, 2025

Add support for OpenAI Connectors and MCP Registries #4061

Open

1 task

jaideepr97 changed the title ~~feat: add readonly connectors API~~ feat(api): add readonly connectors API Nov 28, 2025

jaideepr97 force-pushed the add-connectors-api branch 2 times, most recently from fe03f3e to f711d52 Compare November 28, 2025 18:35

jaideepr97 mentioned this pull request Dec 1, 2025

feat(api): Implement connector support via static configuration #4263

Open

cdoern reviewed Dec 1, 2025

View reviewed changes

jaideepr97 force-pushed the add-connectors-api branch from f711d52 to 4cf2f32 Compare December 1, 2025 19:25

jaideepr97 force-pushed the add-connectors-api branch from 4cf2f32 to ca6068d Compare December 1, 2025 20:22

ashwinb reviewed Dec 1, 2025

View reviewed changes

src/llama_stack_api/registries.py Outdated Show resolved Hide resolved

ashwinb reviewed Dec 1, 2025

View reviewed changes

src/llama_stack_api/registries.py Outdated Show resolved Hide resolved

ashwinb requested changes Dec 1, 2025

View reviewed changes

src/llama_stack_api/resource.py Outdated Show resolved Hide resolved

jaideepr97 force-pushed the add-connectors-api branch 3 times, most recently from 6e939b3 to 565df6c Compare December 2, 2025 05:27

ashwinb requested changes Dec 2, 2025

View reviewed changes

jaideepr97 force-pushed the add-connectors-api branch 4 times, most recently from e3b87d9 to 8d93b53 Compare December 3, 2025 18:16

ashwinb requested changes Dec 3, 2025

View reviewed changes

jaideepr97 force-pushed the add-connectors-api branch 2 times, most recently from 0eab243 to 8082317 Compare December 4, 2025 17:55

ashwinb reviewed Dec 4, 2025

View reviewed changes

jaideepr97 force-pushed the add-connectors-api branch from 8082317 to 3f93a61 Compare December 5, 2025 15:51

jaideepr97 force-pushed the add-connectors-api branch from 3f93a61 to 5949507 Compare December 8, 2025 14:40

jaideepr97 force-pushed the add-connectors-api branch from 5949507 to de26e6b Compare December 8, 2025 15:58

jaideepr97 added 3 commits December 10, 2025 22:46

feati(api): add connectors API

b7f58d3

Closes llamastack#4235 and llamastack#4061 (partially) Signed-off-by: Jaideep Rao <[email protected]>

add creation/updation timestamps to resource base class, exclude auth…

8916686

… info from connectors api response Signed-off-by: Jaideep Rao <[email protected]>

remove auth fields and extract common connectorfields

980f4b8

Signed-off-by: Jaideep Rao <[email protected]>

jaideepr97 force-pushed the add-connectors-api branch from de26e6b to 980f4b8 Compare December 10, 2025 17:16

ashwinb reviewed Dec 10, 2025

View reviewed changes

ashwinb approved these changes Dec 10, 2025

View reviewed changes

feat(api): add readonly connectors API #4258

Are you sure you want to change the base?

feat(api): add readonly connectors API #4258

Uh oh!

Conversation

jaideepr97 commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Test Plan

Uh oh!

cdoern left a comment

Choose a reason for hiding this comment

Uh oh!

jaideepr97 commented Dec 1, 2025

Uh oh!

leseb commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jaideepr97 commented Dec 1, 2025

Uh oh!

github-actions bot commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds

Uh oh!

ashwinb commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ashwinb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leseb commented Dec 4, 2025

Uh oh!

jaideepr97 commented Dec 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

jaideepr97 commented Nov 28, 2025 •

edited

Loading

leseb commented Dec 1, 2025 •

edited

Loading

github-actions bot commented Dec 1, 2025 •

edited

Loading

ashwinb commented Dec 1, 2025 •

edited

Loading