CrewAI tools: built-ins, custom tools and MCP

Setup, step by step

1. Step 1

   Create an agent key for the crew

   In the Locus Pro dashboard, open Connect, then API keys, then An agent. Allow only the tools the crew needs, set a credit cap per call and an expiry. Keep the lcac_ key in your secret manager, not in agents.yaml or the repo.

   export LOCUS_AGENT_CONNECTION="lcac_..."   # agent key, from your secret store
   export LOCUS_MCP_URL="https://api.paywithlocus.com/api/credits/mcp"

2. Step 2

   Install CrewAI and the MCP library

   CrewAI needs Python 3.10 or later and below 3.14. The mcps field on an agent needs the mcp library in your project.

   uv tool install crewai
   uv add mcp

3. Step 3

   Add Locus Pro to an agent

   MCPServerHTTP takes the URL, headers and streamable=True for Streamable HTTP. The static tool filter exposes only the four Locus tools the agent needs.

   import os
   from crewai import Agent
   from crewai.mcp import MCPServerHTTP
   from crewai.mcp.filters import create_static_tool_filter
   
   locus = MCPServerHTTP(
       url=os.environ["LOCUS_MCP_URL"],
       headers={"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"},
       streamable=True,
       tool_filter=create_static_tool_filter(
           allowed_tool_names=["search_apis", "describe_api", "execute", "get_balance"]
       ),
   )
   
   researcher = Agent(
       role="Account Researcher",
       goal="Profile target companies with paid data tools",
       backstory="Uses Locus Pro tools and reports what each call cost.",
       mcps=[locus],
   )

4. Step 4

   Run a task with a price ceiling

   Name the endpoint and max_credits in the task. The execute result reports credits_charged and credits_balance, so ask for them in the expected output.

   from crewai import Crew, Task
   
   task = Task(
       description="Get company data for stripe.com with hunter/company-enrichment. Pass max_credits 15.",
       expected_output="Industry, employee count and the credits charged.",
       agent=researcher,
   )
   result = Crew(agents=[researcher], tasks=[task]).kickoff()
   print(result)

5. Step 5

   Check the crew ran with Locus tools

   If the server fails to connect, CrewAI logs a warning and the agent runs without those tools. Check the log, and check that result.tool_failures is empty before you trust the output.

Where do CrewAI tools come from?

CrewAI gives agents tools from three sources, and the Locus Pro server is one kind of MCP server, shown in its own row. The difference that matters for cost is who holds the provider account. The CrewAI docs' own example sets SERPER_API_KEY before it uses SerperDevTool, so a provider-backed tool brings that provider's account and bill.

Should I use the mcps field or MCPServerAdapter?

Use the mcps field with MCPServerHTTP. CrewAI recommends the mcps field, and MCPServerHTTP documents a headers argument, which is how Locus Pro reads the agent key.

A plain URL string in mcps works for servers that take a key in the query string. Locus Pro reads the key from the Authorization header, and keys in URLs leak into logs, so use the structured form.

MCPServerAdapter from crewai-tools is for manual connection control. Its Streamable HTTP examples show only url and transport keys, so the docs do not show where a bearer header goes. That makes MCPServerHTTP the documented path for Locus Pro.

What does a sales research crew cost through Locus Pro?

Prices come from the Locus catalog. 1,000 credits equal $1. Search, describe and balance checks are free. Prices checked November 10, 2026.

A worked example: profile 50 accounts with 1 company enrichment and 1 people search each. That is 50 x 10.1 + 50 x 2 = 605 credits, about $0.61. Add an email lookup for 3 contacts per account, 150 calls at up to 10.1 credits, and the worst case rises to 2,120 credits, about $2.12.

• Find leads cheaply
• Find an email address

How do I cap spend per tool call in CrewAI?

The agent key is the hard limit. Its per-call cap is checked by Locus, and a call priced above it fails with agent_connection_call_limit_exceeded before anything runs. The key also limits which endpoints the crew can call at all.

Inside a task, ask for max_credits on each execute call. A call above the ceiling fails with nothing charged. The model writes that number, so keep the key cap as the backstop.

On the CrewAI side, set tool_failure_policy to raise when a refused paid call should stop the crew. CrewAI also stops an agent that repeats the same call with the same result five times in a row, which ends a loop that keeps hitting a refused call.

What happens when the Locus server or a paid call fails?

Connection failures do not stop the crew. CrewAI logs a warning and runs the agent with the tools it could load, and connections time out after 30 seconds by default. A crew can finish without ever reaching Locus, so read the log.

A Locus error comes back as an MCP result with isError set. CrewAI records it as a tool failure. The default policy is warn: it records the failure and continues. Check tool_failures on the crew output, since a crew can succeed with failures in that list.

When should a crew use built-in tools instead of Locus Pro?

Use a built-in tool when one provider covers the job and volume is steady. That provider can cost less per call with your own account and API key, which the built-in tool already expects.

Use Locus Pro when a crew needs several data providers, such as enrichment, search and scraping, and you want one key, one balance and a ceiling per call. It also fits crews that run now and then, since there is no plan minimum.

• Clay alternative for agent enrichment
• Add Locus to any MCP client
• Browse the tool catalog