fix archestra__get_mcp_gateway tool and check other archestra__ tools

[iskhakov]

Please send a video demo with the chat where you test all archestra__ tools

[iskhakov]

/bounty 30

[algora-pbc]

💎 $30 bounty • Archestra

Steps to solve:

1. Comment /attempt #3214 with your implementation plan
2. Make sure you're assigned to the issue by the core team member.
3. Start working: Read contribution guideline: https://www.archestra.ai/docs/contributing
4. Submit work: Create a pull request including /claim #3214 in the PR body to claim the bounty
5. Receive payment: 100% of the bounty is received 2-5 days post-reward. Make sure you are eligible for payouts

Thank you for contributing to archestra-ai/archestra!

Attempt	Started (UTC)	Solution	Actions
🟢 @Rutetid	Mar 09, 2026, 08:35:21 PM	WIP
🟢 @samuel-asleep	Mar 09, 2026, 09:32:11 PM	WIP
🟢 @yodakohl	Mar 09, 2026, 10:52:39 PM	#3223	Reward
🟢 @kevinpsj0	Mar 09, 2026, 10:46:51 PM	#3222	Reward

[Rutetid]

/attempt #3214

[London-Cat]

📊 Reputation Summary

User	Rep	Pull Requests	Activity	Assigned	Core Reactions
iskhakov	⚡ 1810	77✅ 0🔄 23❌	100 issues, 50 comments	3	—
Rutetid	⚡ 50	3✅ 0🔄 1❌	0 issues, 22 comments	0	—
yodakohl	⚡ 3	0✅ 1🔄 0❌	0 issues, 1 comments	0	—
rhyk7	⚡ 0	0✅ 0🔄 0❌	0 issues, 1 comments	0	—
samuel-asleep	⚡ 0	0✅ 0🔄 0❌	0 issues, 4 comments	0	—

---

How is the score calculated? Read about it in the Reputation Bot repository 🤖

[samuel-asleep]

/attempt #3214 @iskhakov @Matvey-Kuk please assign

[samuel-asleep]

Implementation Plan: Fix archestra__get_mcp_gateway (and related get tools)

Problem Location

File: platform/backend/src/archestra-mcp-server.ts, lines ~1714–1735

The archestra__get_mcp_gateway, archestra__get_agent, and archestra__get_llm_proxy tools all share the same handler. When the id parameter is provided, it is passed directly to AgentModel.findById(id):

if (id) {
  record = await AgentModel.findById(id);  // ❌ No UUID validation
}

AgentModel.findById runs the following SQL:

SELECT ... FROM "agents" ... WHERE "agents"."id" = $1
-- params: "n8n workflow: Grafana exporter"  ← NOT a UUID!

Because agents.id is a uuid column in PostgreSQL, passing a human-readable name string causes the query to fail with an error. The user sees:

"An unexpected error occurred. Please try again."

This happens when an LLM (or user) passes a name as the id field instead of a valid UUID — e.g., { "id": "n8n workflow: Grafana exporter" }.

---

Root Cause

No validation is performed on the id argument before it is used in a UUID-keyed database lookup. The tool's description already documents support for both id and name parameters, and a name-search fallback via AgentModel.findAllPaginated is already implemented — but it is only reached when id is absent entirely.

---

Proposed Fix

1. Add a UUID validation utility

File: platform/backend/src/utils/db.ts

const UUID_REGEX =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function isValidUUID(value: string): boolean {
  return UUID_REGEX.test(value);
}

2. Use UUID validation in the get-entity handler

File: platform/backend/src/archestra-mcp-server.ts

Import isValidUUID and update the handler logic so that a non-UUID id falls back to name search:

// Before (broken):
if (id) {
  record = await AgentModel.findById(id);
} else if (name) {
  // name search ...
}

// After (fixed):
if (id && isValidUUID(id)) {
  record = await AgentModel.findById(id);
} else if (id || name) {
  // If id is not a valid UUID, treat it as a name search.
  const searchName = (id && !isValidUUID(id) ? id : name) as string;
  const results = await AgentModel.findAllPaginated(
    { limit: 1, offset: 0 },
    undefined,
    { name: searchName, agentType: expectedType, scope: "personal",
      authorIds: context.userId ? [context.userId] : [] },
    context.userId,
    true,
  );
  if (results.data.length > 0) {
    record = results.data[0];
  }
}

---

Affected Tools

All three tools share the same handler block and are fixed by this single change:

Tool	Type filter
archestra__get_mcp_gateway	mcp_gateway
archestra__get_agent	agent
archestra__get_llm_proxy	llm_proxy

---

[iskhakov]

@samuel-asleep please write with normal human language here. Your suggestion looks good, what do you think if we add search by name as well?

[yodakohl]

/attempt #3214

Implementation plan:

• treat non-UUID id input in the shared get_mcp_gateway / get_agent / get_llm_proxy handler as a name lookup instead of sending it into AgentModel.findById
• keep UUID lookups unchanged
• add regression tests for all three tool paths when the model passes a name through the id field

[samuel-asleep]

@samuel-asleep please write with normal human language here. Your suggestion looks good, what do you think if we add search by name as well?

@iskhakov, sorry about the wall of code! Here is the plain-English version of what’s happening and how I’m planning to fix it:

The Problem
Right now, these tools (like get_mcp_gateway) expect a specific technical ID. If an LLM or a user provides a friendly name instead—like 'Grafana exporter'—the database doesn't know how to handle it and just crashes with a generic error message.

The Solution
I want to make the tools a bit more flexible. Instead of just failing when they see a name, the tool will:

1. Check: Is this a technical ID or a name?
2. Act: If it’s a name, it will automatically trigger a search to find the correct agent for the user.

Regarding search by name
I completely agree! That's actually the heart of this fix. By allowing the tool to "fallback" and search by name when a valid ID isn't provided, we make the whole system much more resilient and user-friendly.

Does this summary make sense? If you're happy with this direction, I can open the PR!