Skip to main content
Omnigent is an open-source agent framework that runs Claude Code, Codex, Cursor, and other harnesses behind one interface. It speaks MCP natively, so PipesHub attaches as a standard remote MCP server — no plugin, no fork. Each person uses their own PipesHub personal access token, so results respect their own permissions. Never share one token across a team.
Attach with a bearer token, not an OAuth app. Cursor and Claude Code use a registered OAuth app with a static client ID and secret. Omnigent’s MCP attach takes an Authorization header, and its browser-OAuth path relies on dynamic client registration, which PipesHub does not support — so a PAT is the working credential here.To be clear about identity: an OAuth app using the authorization code flow does run as the signed-in user, exactly like a PAT. It is only client_credentials that has no user identity — see Unattended runs.

​
What you need

Your PipesHub instance must be reachable from wherever the agent runs. A laptop-local instance is fine for a local agent; a hosted or sandboxed runner needs a reachable URL.

​
Create a token

  1. Sign in to PipesHub
  2. Go to Workspace-settings
  3. Select Personal Access Tokens under the Developer Settings section
  4. Click New token, pick an expiry and the default scope set
The token is shown once and starts with phpat_. The panel also gives you a ready-to-paste block containing both values used below.

​
Attach it to a session

The fastest path — no files, no restart of anything but the session:
  1. Open Agent info on the session → Manage MCP servers
  2. Add a server:
    • URL — PIPESHUB_INSTANCE_URL/mcp
    • Header — Authorization: Bearer phpat_…
  3. Restart the session
Ask it something only your organization knows the answer to. If the tools are working, the answer comes back with citations you can open.

​
Or put it in an agent config

For an agent you want to keep or share, declare the server in a directory config. Omnigent expands ${VAR} in both url and headers at parse time, so the file holds no endpoint and no secret and can go in version control:
Then run it:
${VAR} expansion in the url field requires Omnigent v0.10.0 or later. On older versions only headers expands — put the URL in literally, or upgrade.

​
Make it search instead of guess

An agent with search tools will still answer from its own training data unless told not to. Put something like this in the agent’s AGENTS.md:
Without point 4 in particular, a broken connection looks identical to a working one — the agent just answers from general knowledge in the same confident tone.

​
What the agent can do

The full tool list is on Tools Reference. The three that matter most: That last distinction matters. “Summarize the Q3 review” needs the whole document; a search-only tool will confidently summarize whichever fragments it matched.

​
Troubleshooting

Every call returns 401. The token is expired or revoked. Tokens can be revoked from the same page they’re created on, and revocation takes effect immediately. A phpat_-prefixed token returns 401 on an older PipesHub. Instances predating the prefix strip the token differently — upgrade PipesHub, or store the token without the phpat_ prefix until you do. The agent answers but never cites anything. It probably isn’t calling the tools — and on current Omnigent releases a failed MCP connection is not surfaced in the session, so the agent will answer from general knowledge in the same confident tone. Verify the endpoint with the curl below, and add instruction 4 above so the agent reports tool failures instead of silently continuing. Tools appear but return nothing. Check the token’s scopes — a token only does what you granted it at creation. Verify the endpoint independently of Omnigent:
A 401 here means the credential is the problem, not the agent.

​
Unattended runs

For CI or scheduled jobs where no specific person is asking, an OAuth app with client_credentials is the right shape — see OAuth 2.0 Applications.
A client_credentials token has no user identity. It is not filtered per person, so it should never back an agent that several people query. Use a personal access token for anything user-facing.