Bundles

By default, your agent can see and use all the MCP servers available in Toolhouse. Sometimes you want agents to have access only to specific servers. You can do so with Bundles.

Bundles help you define groups of MCP servers you want to pass to the LLM based on specific contextual need of each agent. For example, let's say you need to create an agent whose only role is to search the web for information about certain companies. Instead of using MCP servers available, the agent will only need to use scraping and browsing servers. In cases like this, you can create a Bundle to restrict the agent to only perform those actions.

Bundles are effective in improving accuracy of the agent, because they only give your agent a subset of all the servers available. They're also a good way to keep your context tidy by not exposing unneeded servers.

Bundles are also useful in many other cases:

• Environments. You can create separate Bundles with MCP servers for development, staging, and production.

• Provider-specific servers. You can create Bundles of MCP servers based on a specific model or provider.

• Testing and evaluation. You can create different collections to evaluate the behaviors of an LLM when passing different MCP servers.

By default, all MCP servers in Toolhouse are installed to a default collection. In the SDK, when you call get_tools() with no arguments, you're implicitly calling the default collection.

from toolhouse import Toolhouse
from groq import Groq

th = Toolhouse()
client = Groq()
MODEL = "llama-3.2-11b-vision-preview"

response = client.chat.completions.create(
  model=MODEL,
  messages=messages,
  # Defaults to 'default'
  tools=th.get_tools(),
)

Create a Bundle

To create a Bundle, go to the Bundles page, then click Create New Bundle.

Then, give a name to your Bundle. This name can be any string up to 128 characters long. The Bundle name will be the identifier you will pass to get_tools to pass the bundle to your LLM.

After choosing a name, you can select the MCP servers you want to add to your Bundle. You will need to choose at least one tool in order to save it.

Once you're done, click Create.

Use a Bundle

In order to use a Bundle, you need to pass the identifier you created to get_tools. Make sure the identifier reflects any uppercase letters or spaces the name of the Bundle may have.

For example, if you chose financial_tools as your bundle name earlier, you will call th.get_tools(bundle="financial_tools").

The aforementioned code example will now look like this:

from toolhouse import Toolhouse
from groq import Groq

th = Toolhouse()
client = Groq()
MODEL = "llama-3.2-11b-vision-preview"

response = client.chat.completions.create(
  model=MODEL,
  messages=messages,
  # Passing a Bundle
  tools=th.get_tools("YOUR_BUNDLE_NAME"),
)

Edit a Bundle

You can add or remove MCP servers from a Bundle, or change its name. To edit a Bundle, go to the Bundles page. Locate the Bundle you want to edit, then click Edit.

Make the requested changes and click Update.

You won't be able to update a Bundle if you remove all MCP servers from it. Make sure you have at least one MCP server in your Bundle in order to update it.

Delete a Bundle

To delete a Bundle, go to the Bundles page. Locate the Bundle you want to delete, then click Delete. Confirm the operation to actually delete the Bundle.

Deleting a Bundle cannot be undone. Ensure you are not using the Bundle in production before proceeding.

Naming your Bundles

Bundles are very flexible and you can adapt them to a lot of scenarios. For example, you can use them to separate concerns between environments, for testing and evaluations, or to equip different models with specific sets of MCP servers.

Choosing the right naming format

Name by environment

You can create one Bundle per environment, and name them for example prod, staging, dev. This is useful if you don't need to version your Bundles, and it allows you to test changes on an environment before making changes to the others.

Development

response = client.chat.completions.create(
  model=MODEL,
  messages=messages,
  tools=th.get_tools("dev"),
)

Staging

response = client.chat.completions.create(
  model=MODEL,
  messages=messages,
  tools=th.get_tools("staging"),
)

Production

response = client.chat.completions.create(
  model=MODEL,
  messages=messages,
  tools=th.get_tools("prod"),
)

Name by version

You can create one Bundle per version, for example v1, v2, v3 and so on. All Bundles will be shared across environments, but you will still be able to test out your changes in an development environment before promoting to production. This is useful if you use the same MCP servers across each LLM.

• Set a configuration variable (for example TOOLHOUSE_BUNDLE_VERSION environment variable) in each of your environments. Each environment can point to a different version.

• Every time you want make a change, you can create a new Bundle or duplicate the Bundle with the latest version number. Increment the version number on this Bundle; for example, if you are duplicating v3, your new Bundle name should be v4.

• Set the TOOLHOUSE_BUNDLE_VERSION variable of your test environment (e.g. development) to this new version.

• Make your changes in your BUNDLE.

• When you're confident with your changes, set the TOOLHOUSE_BUNDLE_VERSION variable in production to this new version.

# In dev
TOOLHOUSE_COLLECTION_VERSION=v4

# In prod
TOOLHOUSE_COLLECTION_VERSION=v3

response = client.chat.completions.create(
  model=MODEL,
  messages=messages,
  # Uses v3 in production, v4 in dev
  tools=th.get_tools(os.environ.get("TOOLHOUSE_BUNDLE_VERSION")),
)

Group by functionality, version, and environment

You can use a naming convention such as bundle_name-version-env, for example crm_lookup_and_search-v1-dev-alice. This way you can logically group functionality while also keeping the benefit of versioning and environment choice.

You can also create a bundle for a specific LLM, for example memory_llama3.1-8b_v1, which allows you to give each LLM different MCP servers. This strategy is effective when some LLM tend to pick the wrong MCP servers, or hallucinate on a server name.